Bmad MCP Server

🚀 BMAD-MCP

BMAD-MCP 是一款遵循 MCP（模型上下文协议）的服务器，作为具备商业思维的敏捷开发（Business-Minded Agile Development）工作流编排器。它涵盖了完整的敏捷开发工作流：产品负责人（PO）→ 架构师 → Scrum 主管（SM）→ 开发人员 → 代码审查员 → 质量保证人员（QA）。

其具备以下特性：

• 交互式需求收集：通过询问澄清问题，确保需求完整。
• 动态引擎选择：默认使用 Claude，必要时采用双引擎。
• 内容引用系统：通过文件引用高效使用令牌。
• 易读的任务名称：按任务名称而非 UUID 进行组织。

🚀 快速开始

安装（3 步）

# 步骤 1：从 npm 全局安装
npm install -g bmad-mcp

# 步骤 2：添加到 Claude Code
claude mcp add-json --scope user bmad '{"type":"stdio","command":"bmad-mcp"}'

# 步骤 3：验证安装
bmad-mcp
# 预期输出："BMAD MCP Server running on stdio"

完成以上步骤后，重启 Claude Code 即可开始使用 BMAD 工作流。

使用示例

只需告知 Claude Code 使用 BMAD：

用户：使用 bmad-task 创建一个用户认证系统

Claude Code 将执行以下操作：
1. 启动 BMAD 工作流（产品负责人阶段）
2. 生成产品需求文档（通过交互式问答）
3. 生成系统架构（通过交互式问答）
4. 创建 Sprint 计划
5. 实现代码（使用 Codex）
6. 进行代码审查
7. 运行质量保证测试

所有工件将保存到：.claude/specs/user-authentication-system/

配置位置

MCP 配置会自动添加到 ~/.claude/config.json：

{
  "mcpServers": {
    "bmad": {
      "type": "stdio",
      "command": "bmad-mcp"
    }
  }
}

✨ 主要特性

• 管理工作流状态：明确当前所处阶段以及下一步需求。
• 分发角色提示：为每个角色提供详细提示。
• 保存工件：保存产品需求文档（PRD）、架构、代码、报告等。
• 不调用大语言模型（LLMs）：调用 LLMs 是 Claude Code 的任务。

📦 安装指南

高级安装选项

选项 1：通过 NPM 安装（推荐）

npm install -g bmad-mcp
claude mcp add-json --scope user bmad '{"type":"stdio","command":"bmad-mcp"}'

选项 2：从源代码构建

git clone https://github.com/cexll/bmad-mcp-server
cd bmad-mcp-server
npm install
npm run build
npm link  # 使 bmad-mcp 全局可用

# 添加到 Claude Code
claude mcp add-json --scope user bmad '{"type":"stdio","command":"bmad-mcp"}'

验证安装

# 检查二进制文件是否可用
which bmad-mcp
# 输出：/usr/local/bin/bmad-mcp（或类似路径）

# 直接测试服务器
bmad-mcp
# 预期输出："BMAD MCP Server running on stdio"
# 按 Ctrl+C 退出

# 重启 Claude Code 以加载配置

卸载

# 从 Claude Code 中移除
claude mcp remove bmad

# 卸载 npm 包
npm uninstall -g bmad-mcp

💻 使用示例

基础用法

// 1. 启动工作流
const startResult = await callTool("bmad-task", {
  action: "start",
  cwd: "/path/to/your/project",
  objective: "Implement user login system"
});

const { session_id, task_name, role_prompt, engines } = JSON.parse(startResult.content[0].text);

// 2. 使用引擎执行
if (engines.includes("claude")) {
  const claudeResult = await callClaude(role_prompt);
}
if (engines.includes("codex")) {
  const codexResult = await callCodexMCP(role_prompt);
}

// 3. 提交结果
await callTool("bmad-task", {
  action: "submit",
  session_id: session_id,
  stage: "po",
  claude_result: claudeResult,
  codex_result: codexResult
});

// 4. 确认并继续（统一操作：保存并进入下一阶段）
await callTool("bmad-task", {
  action: "confirm",
  session_id: session_id,
  confirmed: true
});

高级用法

start - 启动新工作流

{
  "action": "start",
  "cwd": "/path/to/project",
  "objective": "Project description"
}

返回结果：

{
  "session_id": "uuid",
  "task_name": "project-description",
  "stage": "po",
  "state": "generating",
  "stage_description": "Product Owner - Requirements Analysis",
  "requires_user_confirmation": true,
  "interaction_type": "awaiting_generation",
  "user_message": "📋 **BMAD 工作流已启动**...",
  "role_prompt": "<complete prompt>",
  "engines": ["claude"],
  "context": {...},
  "pending_user_actions": ["review_and_confirm_generation"]
}

submit - 提交阶段结果

{
  "action": "submit",
  "session_id": "uuid",
  "stage": "po",
  "claude_result": "...",
  "codex_result": "..."
}

当分数 ≥ 90 时的返回结果：

{
  "session_id": "uuid",
  "stage": "po",
  "state": "awaiting_confirmation",
  "score": 92,
  "requires_user_confirmation": true,
  "interaction_type": "user_decision",
  "user_message": "✅ **PRD生成完成**\n质量评分：92/100...",
  "final_draft_summary": "...",
  "final_draft_file": ".bmad-task/temp/uuid/po_final_result_xxx.md",
  "pending_user_actions": ["confirm", "reject_and_refine"]
}

当分数 < 90 且有澄清问题时的返回结果：

{
  "session_id": "uuid",
  "stage": "po",
  "state": "clarifying",
  "current_score": 75,
  "requires_user_confirmation": true,
  "interaction_type": "user_decision",
  "user_message": "⚠️ **需求澄清...**",
  "gaps": ["Target user group unclear", "..."],
  "questions": [{"id": "q1", "question": "...", "context": "..."}],
  "pending_user_actions": ["answer_questions"]
}

confirm - 确认并保存（统一操作）

{
  "action": "confirm",
  "session_id": "uuid",
  "confirmed": true
}

返回结果（保存工件并进入下一阶段）：

{
  "session_id": "uuid",
  "stage": "architect",
  "state": "generating",
  "requires_user_confirmation": true,
  "interaction_type": "awaiting_generation",
  "user_message": "💾 **文档已保存，并已进入下一阶段**...",
  "role_prompt": "<architect prompt>",
  "engines": ["claude"],
  "previous_artifact": ".claude/specs/task-name/01-product-requirements.md",
  "pending_user_actions": ["review_and_confirm_generation"]
}

answer - 回答澄清问题

{
  "action": "answer",
  "session_id": "uuid",
  "answers": {
    "q1": "Target users are enterprise B2B customers",
    "q2": "Expected 10k concurrent users with <200ms response time"
  }
}

返回结果：

{
  "session_id": "uuid",
  "stage": "po",
  "state": "refining",
  "requires_user_confirmation": true,
  "interaction_type": "awaiting_regeneration",
  "user_message": "📝 **已收到你的回答**...",
  "role_prompt": "<updated prompt with user answers>",
  "engines": ["claude"],
  "pending_user_actions": ["regenerate_with_answers"]
}

approve - 批准当前阶段（仅适用于 Scrum 主管阶段）

{
  "action": "approve",
  "session_id": "uuid",
  "approved": true
}

进入开发阶段时的返回结果：

{
  "session_id": "uuid",
  "stage": "dev",
  "state": "generating",
  "requires_user_confirmation": true,
  "interaction_type": "awaiting_generation",
  "user_message": "✅ **Sprint Plan 已批准**\n\n正在进入下一阶段：Developer - Implementation\n\nSprint Plan 包含 3 个 Sprint：\n1. Sprint 1: 基础架构\n2. Sprint 2: 核心功能\n3. Sprint 3: 优化和完善\n\n⚠️ 重要：请明确指示开发范围...",
  "role_prompt": "<dev prompt>",
  "engines": ["codex"],
  "pending_user_actions": ["specify_sprint_scope_then_generate"]
}

重要 - 开发阶段说明：

• 批准 Sprint 计划后，工作流进入开发阶段，但不会自动开始开发。
• 用户必须明确指定开发范围：
  • “开始开发” / “start development” → 实现所有 Sprint（默认）
  • “开发 Sprint 1” / “implement sprint 1” → 仅实现 Sprint 1
• 这样可确保用户完全控制开发内容和时间。

status - 查询工作流状态

{
  "action": "status",
  "session_id": "uuid"
}

返回结果：

{
  "session_id": "uuid",
  "current_stage": "dev",
  "current_state": "generating",
  "stages": {...},
  "artifacts": [...]
}

📚 详细文档

架构

用户 → Claude Code → bmad-mcp 工具
                       ↓
            返回结果: {
              stage: "po",
              role_prompt: "<完整的产品负责人提示>",
              engines: ["claude", "codex"],
              context: {...}
            }
                       ↓
Claude Code 执行操作:
  - 调用 Claude（使用角色提示）
  - 调用 Codex MCP（使用角色提示）
                       ↓
Claude Code 提交结果 → bmad-mcp
                       ↓
bmad-mcp: 合并、评分、保存结果，并进入下一阶段

工作流阶段

文件结构

项目结构

your-project/
├── .bmad-task/
│   ├── session-abc-123.json          # 工作流状态（包含内容引用）
│   ├── task-mapping.json             # 将 session_id 映射到任务名称
│   └── temp/
│       └── abc-123/                  # 临时内容文件
│           ├── po_claude_result_xxx.md
│           ├── po_codex_result_xxx.md
│           └── po_final_result_xxx.md
├── .claude/
│   └── specs/
│       └── implement-user-login/     # 任务名称（易读的短名称）
│           ├── 01-product-requirements.md
│           ├── 02-system-architecture.md
│           ├── 03-sprint-plan.md
│           ├── 04-dev-reviewed.md
│           └── 05-qa-report.md
└── src/

会话状态文件

{
  "session_id": "abc-123",
  "task_name": "implement-user-login",
  "cwd": "/path/to/project",
  "objective": "Implement user login",
  "current_stage": "dev",
  "current_state": "generating",
  "stages": {
    "po": {
      "status": "completed",
      "claude_result_ref": {
        "summary": "前 300 个字符...",
        "file_path": ".bmad-task/temp/abc-123/po_claude_result_xxx.md",
        "size": 12450,
        "last_updated": "2025-01-15T10:30:00Z"
      },
      "final_result_ref": {...},
      "score": 92,
      "approved": true
    },
    ...
  },
  "artifacts": [".claude/specs/implement-user-login/01-product-requirements.md", ...]
}

引擎配置

产品负责人和架构师阶段（动态引擎选择）

• 默认情况：仅使用 Claude（单引擎）。
• 双引擎情况：当目标中包含 “codex” 或 “使用 codex” 时启用。
• 若启用双引擎：
  • 同时调用 Claude 和 Codex。
  • 每个引擎生成独立的解决方案。
  • BMAD-MCP 合并结果：
    • 若两者分数均 ≥ 90：选择分数较高的结果。
    • 若其中一个分数 ≥ 90：选择该结果。
    • 若两者分数均 < 90：选择分数较高的结果并进行优化。
• 交互式澄清：
  • 第一轮迭代：识别差距，生成 3 - 5 个澄清问题。
  • 用户回答问题。
  • 根据回答重新生成内容。
  • 迭代直至分数 ≥ 90。

Scrum 主管阶段（仅使用 Claude）

仅调用 Claude，因为 Scrum 计划不需要 Codex。

开发/审查/质量保证阶段（仅使用 Codex）

• 仅调用 Codex MCP。
• 代码任务使用 GPT - 5。
• 重要：使用 model: "gpt-5"（而非 “gpt - 5 - codex”）。
• 参数：
  • model: "gpt-5"
  • sandbox: "danger-full-access"
  • approval-policy: "on-failure"

工作流流程

graph TD
    A[开始] --> B[产品负责人阶段：生成]
    B --> C{是否有问题?}
    C -->|是| D[澄清阶段：用户回答]
    D --> E[优化阶段：重新生成]
    E --> F{分数 ≥ 90?}
    C -->|否| F
    F -->|否| C
    F -->|是| G[等待确认]
    G -->|确认| H[保存并进入架构师阶段]
    H --> I{是否有问题?}
    I -->|是| J[澄清阶段：用户回答]
    J --> K[优化阶段：重新生成]
    K --> L{分数 ≥ 90?}
    I -->|否| L
    L -->|否| I
    L -->|是| M[等待确认]
    M -->|确认| N[保存并进入 Scrum 主管阶段]
    N -->|批准| O[开发阶段]
    O --> P[审查阶段]
    P --> Q[质量保证阶段]
    Q --> R[完成]

🔧 技术细节

项目结构

bmad-mcp/
├── src/
│   ├── index.ts              # 主 MCP 服务器
│   └── master-prompt.ts      # 所有角色提示
├── dist/                     # 编译输出
├── package.json
├── tsconfig.json
└── README.md

构建

npm run build

开发模式

npm run dev  # 监听模式

本地测试

npm run build
node dist/index.js

主编排器设计

所有角色提示都嵌入在单个 master-prompt.ts 文件中：

• 集中管理：所有角色提示集中在一处。
• 工作流定义：明确阶段顺序。
• 引擎配置：指定每个阶段使用的引擎。
• 质量关卡：设定分数阈值和批准点。

与 Codex MCP 集成

在开发/审查/质量保证阶段调用 Codex 时：

// Claude Code 调用 Codex MCP
await callTool("codex", {
  prompt: role_prompt,  // 来自 bmad-task
  model: "gpt-5",  // 重要：使用 "gpt-5"，而非 "gpt-5-codex"
  sandbox: "danger-full-access",
  "approval-policy": "on-failure"
});

配置

质量阈值

在 master-prompt.ts 中定义：

quality_gates: {
  po: { min_score: 90, approval_required: true },
  architect: { min_score: 90, approval_required: true },
  sm: { approval_required: true },
  dev: {},
  review: {},
  qa: {}
}

工件文件名

artifacts: {
  po: "01-product-requirements.md",
  architect: "02-system-architecture.md",
  sm: "03-sprint-plan.md",
  dev: "code-implementation",
  review: "04-dev-reviewed.md",
  qa: "05-qa-report.md"
}

🔍 故障排除

服务器无法启动

# 检查安装情况
which bmad-mcp

# 直接测试
bmad-mcp

工具名称错误

• 重要：工具名称是 bmad-task，而非 bmad。
• 在代码中使用 callTool("bmad-task", {...})。
• Claude Code 配置应使用 bmad-task 作为工具名称。

会话未找到

• 确保 .bmad-task/ 目录具有写入权限。
• 检查 session_id 是否正确。
• 验证 cwd 路径是否为绝对路径。

分数未检测到

• 确保生成的内容包含：Quality Score: X/100 或 JSON 中的 "quality_score": 92。
• 检查分数格式是否符合模式（0 - 100）。
• 产品负责人/架构师阶段需要分数 ≥ 90 才能进入下一阶段。

澄清工作流问题

• 若看到 state: "clarifying"，用户必须通过 answer 操作回答问题。
• 不要自动生成答案，等待用户的真实输入。
• 在继续操作前，检查 requires_user_confirmation: true。

📄 许可证

本项目采用 MIT 许可证。

🙋 支持

• 文档：本 README 文件。
• 问题反馈：GitHub 问题。
• 参考资料：https://github.com/cexll/myclaude

使用 BMAD 变革你的开发流程 —— 一套工作流，涵盖完整敏捷过程，确保开发质量。