BMAD-MCP

Business-Minded Agile Development workflow orchestrator as an MCP (Model Context Protocol) server.

Complete agile development workflow: PO → Architect → SM → Dev → Review → QA

Interactive Requirements Gathering - Asks clarifying questions to ensure complete requirements Dynamic Engine Selection - Uses Claude by default, dual-engine when needed Content Reference System - Efficient token usage via file references Human-Readable Task Names - Organizes by task name, not UUID

🎯 What is BMAD-MCP?

BMAD-MCP is a lightweight workflow orchestrator that manages the complete agile development process. It:

Manages workflow state (which stage you're in, what's needed next)
Dispatches role prompts (provides detailed prompts for each role)
Saves artifacts (PRD, architecture, code, reports)
Does NOT call LLMs (that's Claude Code's job)

🏗️ Architecture

hljs language-css

User → Claude Code → bmad-mcp tool
                       ↓
            Returns: {
              stage: "po",
              role_prompt: "<complete PO prompt>",
              engines: ["claude", "codex"],
              context: {...}
            }
                       ↓
Claude Code executes:
  - Calls Claude (with role_prompt)
  - Calls Codex MCP (with role_prompt)
                       ↓
Claude Code submits results → bmad-mcp
                       ↓
bmad-mcp: merges, scores, saves, advances to next stage

📋 Workflow Stages

Stage	Role	Engines	Description
PO	Product Owner	Claude + Codex	Requirements analysis (merge both)
Architect	System Architect	Claude + Codex	Technical design (merge both)
SM	Scrum Master	Claude	Sprint planning
Dev	Developer	Codex	Code implementation
Review	Code Reviewer	Codex	Code review
QA	QA Engineer	Codex	Testing and quality assurance

🚀 Quick Start

Installation (3 Steps)

hljs language-bash

# Step 1: Install globally from npm
npm install -g bmad-mcp

# Step 2: Add to Claude Code
claude mcp add-json --scope user bmad '{"type":"stdio","command":"bmad-mcp"}'

# Step 3: Verify installation
bmad-mcp
# Expected output: "BMAD MCP Server running on stdio"

That's it! Restart Claude Code and you're ready to use BMAD workflow.

Usage Example

Simply tell Claude Code to use BMAD:

hljs language-sql

User: Use bmad-task to create a user authentication system

Claude Code will:
1. Start BMAD workflow (PO stage)
2. Generate Product Requirements Document (with interactive Q&A)
3. Generate System Architecture (with interactive Q&A)
4. Create Sprint Plan
5. Implement code (using Codex)
6. Perform code review
7. Run quality assurance tests

All artifacts saved to: .claude/specs/user-authentication-system/

Configuration Location

MCP configuration is automatically added to ~/.claude/config.json:

hljs language-json

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

🔧 Advanced Installation

Option 1: NPM Install (Recommended)

hljs language-bash

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

Option 2: Build from Source

hljs language-bash

git clone https://github.com/cexll/bmad-mcp-server
cd bmad-mcp-server
npm install
npm run build
npm link  # Makes bmad-mcp globally available

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

Verify Installation

hljs language-bash

# Check if binary is available
which bmad-mcp
# Output: /usr/local/bin/bmad-mcp (or similar)

# Test the server directly
bmad-mcp
# Expected output: "BMAD MCP Server running on stdio"
# Press Ctrl+C to exit

# Restart Claude Code to load the configuration

Uninstall

hljs language-bash

# Remove from Claude Code
claude mcp remove bmad

# Uninstall npm package
npm uninstall -g bmad-mcp

📖 Usage

Basic Workflow

hljs language-typescript

// 1. Start workflow
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. Execute with engines
if (engines.includes("claude")) {
  const claudeResult = await callClaude(role_prompt);
}
if (engines.includes("codex")) {
  const codexResult = await callCodexMCP(role_prompt);
}

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

// 4. Confirm and proceed (unified: saves + advances to next stage)
await callTool("bmad-task", {
  action: "confirm",
  session_id: session_id,
  confirmed: true
});

Actions

`start` - Start a new workflow

hljs language-json

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

Returns:

hljs language-json

{
  "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` - Submit stage results

hljs language-json

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

Returns (if score >= 90):

hljs language-json

{
  "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"]
}

Returns (if score < 90 with clarification questions):

hljs language-json

{
  "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` - Confirm and save (unified action)

hljs language-json

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

Returns (saves artifact + advances to next stage):

hljs language-json

{
  "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` - Answer clarification questions

hljs language-json

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

Returns:

hljs language-json

{
  "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` - Approve current stage (SM stage only)

hljs language-json

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

Returns (when entering Dev stage):

hljs language-json

{
  "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"]
}

Important - Dev Stage Behavior:

After approving Sprint Plan, workflow enters Dev stage but does NOT auto-start development
User must explicitly specify development scope:
- "开始开发" / "start development" → Implements ALL sprints (default)
- "开发 Sprint 1" / "implement sprint 1" → Implements only Sprint 1
This ensures users have full control over what gets implemented and when

`status` - Query workflow status

hljs language-json

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

Returns:

hljs language-json

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

📁 File Structure

Your Project

hljs language-perl

your-project/
├── .bmad-task/
│   ├── session-abc-123.json          # Workflow state (with content references)
│   ├── task-mapping.json             # Maps session_id → task_name
│   └── temp/
│       └── abc-123/                  # Temporary content files
│           ├── po_claude_result_xxx.md
│           ├── po_codex_result_xxx.md
│           └── po_final_result_xxx.md
├── .claude/
│   └── specs/
│       └── implement-user-login/     # Task name (human-readable slug)
│           ├── 01-product-requirements.md
│           ├── 02-system-architecture.md
│           ├── 03-sprint-plan.md
│           ├── 04-dev-reviewed.md
│           └── 05-qa-report.md
└── src/

Session State File

hljs language-json

{
  "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": "First 300 chars...",
        "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", ...]
}

🎨 Engine Configuration

PO & Architect Stages (Dynamic Engine Selection)

Default: Only Claude (single engine)
Dual Engine: Enabled when objective contains "codex" or "使用 codex"
If dual engine enabled:
- Calls both Claude and Codex
- Each generates independent solution
- BMAD-MCP merges results:
  - If both ≥ 90: choose higher score
  - If one ≥ 90: choose that one
  - If both < 90: choose higher score, refine
Interactive Clarification:
- First iteration: Identify gaps, generate 3-5 clarification questions
- User answers questions
- Regenerate based on answers
- Iterate until score ≥ 90

SM Stage (Claude Only)

Only calls Claude
Scrum planning doesn't need Codex

Dev/Review/QA Stages (Codex Only)

Only calls Codex MCP
Uses GPT-5 for code tasks
Important: Use model: "gpt-5" (NOT "gpt-5-codex")
Parameters:
- model: "gpt-5"
- sandbox: "danger-full-access"
- approval-policy: "on-failure"

🔄 Workflow Flow

hljs language-mermaid

graph TD
    A[Start] --> B[PO Stage: Generate]
    B --> C{Has Questions?}
    C -->|Yes| D[Clarifying: User Answers]
    D --> E[Refining: Regenerate]
    E --> F{Score >= 90?}
    C -->|No| F
    F -->|No| C
    F -->|Yes| G[Awaiting Confirmation]
    G -->|confirm| H[Saved + Architect Stage]
    H --> I{Has Questions?}
    I -->|Yes| J[Clarifying: User Answers]
    J --> K[Refining: Regenerate]
    K --> L{Score >= 90?}
    I -->|No| L
    L -->|No| I
    L -->|Yes| M[Awaiting Confirmation]
    M -->|confirm| N[Saved + SM Stage]
    N -->|approve| O[Dev Stage]
    O --> P[Review Stage]
    P --> Q[QA Stage]
    Q --> R[Complete]

🛠️ Development

Project Structure

hljs language-bash

bmad-mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   └── master-prompt.ts      # All role prompts
├── dist/                     # Compiled output
├── package.json
├── tsconfig.json
└── README.md

Build

hljs language-bash

npm run build

Development Mode

hljs language-bash

npm run dev  # Watch mode

Test Locally

hljs language-bash

npm run build
node dist/index.js

📚 Master Orchestrator Design

All role prompts are embedded in a single master-prompt.ts file:

Centralized management: All roles in one place
Workflow definition: Clear stage sequence
Engine configuration: Which engines for each stage
Quality gates: Score thresholds and approval points

🤝 Integration with Codex MCP

When calling Codex for Dev/Review/QA stages:

hljs language-typescript

// Claude Code calls Codex MCP
await callTool("codex", {
  prompt: role_prompt,  // From bmad-task
  model: "gpt-5",  // IMPORTANT: Use "gpt-5", NOT "gpt-5-codex"
  sandbox: "danger-full-access",
  "approval-policy": "on-failure"
});

⚙️ Configuration

Quality Thresholds

Defined in master-prompt.ts:

hljs language-typescript

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

Artifact Filenames

hljs language-typescript

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"
}

🔍 Troubleshooting

Server not starting

hljs language-bash

# Check installation
which bmad-mcp

# Test directly
bmad-mcp

Tool name error

Important: The tool name is bmad-task, not bmad
Use callTool("bmad-task", {...}) in your code
Claude Code configuration should use bmad-task as the tool name

Session not found

Ensure .bmad-task/ directory has write permissions
Check session_id is correct
Verify cwd path is absolute

Scores not detected

Ensure generated content includes: Quality Score: X/100 or "quality_score": 92 in JSON
Check score format matches pattern (0-100)
Score ≥ 90 required for PO/Architect stages to advance

Clarification workflow issues

If you see state: "clarifying", user must answer questions via answer action
Do NOT auto-generate answers - wait for real user input
Check requires_user_confirmation: true before proceeding

📝 License

MIT

🙋 Support

Documentation: This README
Issues: GitHub issues
Reference: https://github.com/cexll/myclaude

Transform your development with BMAD - One workflow, complete agile process, quality assured.

BMAD-MCP

Business-Minded Agile Development workflow orchestrator as an MCP (Model Context Protocol) server.

Complete agile development workflow: PO → Architect → SM → Dev → Review → QA

🎯 What is BMAD-MCP?

BMAD-MCP is a lightweight workflow orchestrator that manages the complete agile development process. It:

Manages workflow state (which stage you're in, what's needed next)
Dispatches role prompts (provides detailed prompts for each role)
Saves artifacts (PRD, architecture, code, reports)
Does NOT call LLMs (that's Claude Code's job)

🏗️ Architecture

hljs language-css

User → Claude Code → bmad-mcp tool
                       ↓
            Returns: {
              stage: "po",
              role_prompt: "<complete PO prompt>",
              engines: ["claude", "codex"],
              context: {...}
            }
                       ↓
Claude Code executes:
  - Calls Claude (with role_prompt)
  - Calls Codex MCP (with role_prompt)
                       ↓
Claude Code submits results → bmad-mcp
                       ↓
bmad-mcp: merges, scores, saves, advances to next stage

📋 Workflow Stages

Stage	Role	Engines	Description
PO	Product Owner	Claude + Codex	Requirements analysis (merge both)
Architect	System Architect	Claude + Codex	Technical design (merge both)
SM	Scrum Master	Claude	Sprint planning
Dev	Developer	Codex	Code implementation
Review	Code Reviewer	Codex	Code review
QA	QA Engineer	Codex	Testing and quality assurance

🚀 Quick Start

Installation (3 Steps)

hljs language-bash

# Step 1: Install globally from npm
npm install -g bmad-mcp

# Step 2: Add to Claude Code
claude mcp add-json --scope user bmad '{"type":"stdio","command":"bmad-mcp"}'

# Step 3: Verify installation
bmad-mcp
# Expected output: "BMAD MCP Server running on stdio"

That's it! Restart Claude Code and you're ready to use BMAD workflow.

Usage Example

Simply tell Claude Code to use BMAD:

hljs language-sql

User: Use bmad-task to create a user authentication system

Claude Code will:
1. Start BMAD workflow (PO stage)
2. Generate Product Requirements Document (with interactive Q&A)
3. Generate System Architecture (with interactive Q&A)
4. Create Sprint Plan
5. Implement code (using Codex)
6. Perform code review
7. Run quality assurance tests

All artifacts saved to: .claude/specs/user-authentication-system/

Configuration Location

MCP configuration is automatically added to ~/.claude/config.json:

hljs language-json

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

🔧 Advanced Installation

Option 1: NPM Install (Recommended)

hljs language-bash

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

Option 2: Build from Source

hljs language-bash

git clone https://github.com/cexll/bmad-mcp-server
cd bmad-mcp-server
npm install
npm run build
npm link  # Makes bmad-mcp globally available

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

Verify Installation

hljs language-bash

# Check if binary is available
which bmad-mcp
# Output: /usr/local/bin/bmad-mcp (or similar)

# Test the server directly
bmad-mcp
# Expected output: "BMAD MCP Server running on stdio"
# Press Ctrl+C to exit

# Restart Claude Code to load the configuration

Uninstall

hljs language-bash

# Remove from Claude Code
claude mcp remove bmad

# Uninstall npm package
npm uninstall -g bmad-mcp

📖 Usage

Basic Workflow

hljs language-typescript

// 1. Start workflow
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. Execute with engines
if (engines.includes("claude")) {
  const claudeResult = await callClaude(role_prompt);
}
if (engines.includes("codex")) {
  const codexResult = await callCodexMCP(role_prompt);
}

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

// 4. Confirm and proceed (unified: saves + advances to next stage)
await callTool("bmad-task", {
  action: "confirm",
  session_id: session_id,
  confirmed: true
});

Actions

`start` - Start a new workflow

hljs language-json

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

Returns:

hljs language-json

{
  "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` - Submit stage results

hljs language-json

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

Returns (if score >= 90):

hljs language-json

{
  "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"]
}

Returns (if score < 90 with clarification questions):

hljs language-json

{
  "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` - Confirm and save (unified action)

hljs language-json

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

Returns (saves artifact + advances to next stage):

hljs language-json

{
  "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` - Answer clarification questions

hljs language-json

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

Returns:

hljs language-json

{
  "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` - Approve current stage (SM stage only)

hljs language-json

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

Returns (when entering Dev stage):

hljs language-json

{
  "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"]
}

Important - Dev Stage Behavior:

After approving Sprint Plan, workflow enters Dev stage but does NOT auto-start development
User must explicitly specify development scope:
- "开始开发" / "start development" → Implements ALL sprints (default)
- "开发 Sprint 1" / "implement sprint 1" → Implements only Sprint 1
This ensures users have full control over what gets implemented and when

`status` - Query workflow status

hljs language-json

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

Returns:

hljs language-json

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

📁 File Structure

Your Project

hljs language-perl

your-project/
├── .bmad-task/
│   ├── session-abc-123.json          # Workflow state (with content references)
│   ├── task-mapping.json             # Maps session_id → task_name
│   └── temp/
│       └── abc-123/                  # Temporary content files
│           ├── po_claude_result_xxx.md
│           ├── po_codex_result_xxx.md
│           └── po_final_result_xxx.md
├── .claude/
│   └── specs/
│       └── implement-user-login/     # Task name (human-readable slug)
│           ├── 01-product-requirements.md
│           ├── 02-system-architecture.md
│           ├── 03-sprint-plan.md
│           ├── 04-dev-reviewed.md
│           └── 05-qa-report.md
└── src/

Session State File

hljs language-json

{
  "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": "First 300 chars...",
        "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", ...]
}

🎨 Engine Configuration

PO & Architect Stages (Dynamic Engine Selection)

Default: Only Claude (single engine)
Dual Engine: Enabled when objective contains "codex" or "使用 codex"
If dual engine enabled:
- Calls both Claude and Codex
- Each generates independent solution
- BMAD-MCP merges results:
  - If both ≥ 90: choose higher score
  - If one ≥ 90: choose that one
  - If both < 90: choose higher score, refine
Interactive Clarification:
- First iteration: Identify gaps, generate 3-5 clarification questions
- User answers questions
- Regenerate based on answers
- Iterate until score ≥ 90

SM Stage (Claude Only)

Only calls Claude
Scrum planning doesn't need Codex

Dev/Review/QA Stages (Codex Only)

Only calls Codex MCP
Uses GPT-5 for code tasks
Important: Use model: "gpt-5" (NOT "gpt-5-codex")
Parameters:
- model: "gpt-5"
- sandbox: "danger-full-access"
- approval-policy: "on-failure"

🔄 Workflow Flow

hljs language-mermaid

graph TD
    A[Start] --> B[PO Stage: Generate]
    B --> C{Has Questions?}
    C -->|Yes| D[Clarifying: User Answers]
    D --> E[Refining: Regenerate]
    E --> F{Score >= 90?}
    C -->|No| F
    F -->|No| C
    F -->|Yes| G[Awaiting Confirmation]
    G -->|confirm| H[Saved + Architect Stage]
    H --> I{Has Questions?}
    I -->|Yes| J[Clarifying: User Answers]
    J --> K[Refining: Regenerate]
    K --> L{Score >= 90?}
    I -->|No| L
    L -->|No| I
    L -->|Yes| M[Awaiting Confirmation]
    M -->|confirm| N[Saved + SM Stage]
    N -->|approve| O[Dev Stage]
    O --> P[Review Stage]
    P --> Q[QA Stage]
    Q --> R[Complete]

🛠️ Development

Project Structure

hljs language-bash

bmad-mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   └── master-prompt.ts      # All role prompts
├── dist/                     # Compiled output
├── package.json
├── tsconfig.json
└── README.md

Build

hljs language-bash

npm run build

Development Mode

hljs language-bash

npm run dev  # Watch mode

Test Locally

hljs language-bash

npm run build
node dist/index.js

📚 Master Orchestrator Design

All role prompts are embedded in a single master-prompt.ts file:

Centralized management: All roles in one place
Workflow definition: Clear stage sequence
Engine configuration: Which engines for each stage
Quality gates: Score thresholds and approval points

🤝 Integration with Codex MCP

When calling Codex for Dev/Review/QA stages:

hljs language-typescript

// Claude Code calls Codex MCP
await callTool("codex", {
  prompt: role_prompt,  // From bmad-task
  model: "gpt-5",  // IMPORTANT: Use "gpt-5", NOT "gpt-5-codex"
  sandbox: "danger-full-access",
  "approval-policy": "on-failure"
});

⚙️ Configuration

Quality Thresholds

Defined in master-prompt.ts:

hljs language-typescript

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

Artifact Filenames

hljs language-typescript

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"
}

🔍 Troubleshooting

Server not starting

hljs language-bash

# Check installation
which bmad-mcp

# Test directly
bmad-mcp

Tool name error

Important: The tool name is bmad-task, not bmad
Use callTool("bmad-task", {...}) in your code
Claude Code configuration should use bmad-task as the tool name

Session not found

Ensure .bmad-task/ directory has write permissions
Check session_id is correct
Verify cwd path is absolute

Scores not detected

Ensure generated content includes: Quality Score: X/100 or "quality_score": 92 in JSON
Check score format matches pattern (0-100)
Score ≥ 90 required for PO/Architect stages to advance

Clarification workflow issues

If you see state: "clarifying", user must answer questions via answer action
Do NOT auto-generate answers - wait for real user input
Check requires_user_confirmation: true before proceeding

📝 License

MIT

🙋 Support

Documentation: This README
Issues: GitHub issues
Reference: https://github.com/cexll/myclaude

Transform your development with BMAD - One workflow, complete agile process, quality assured.

bmad-mcp-server

BMAD-MCP

🎯 What is BMAD-MCP?

🏗️ Architecture

📋 Workflow Stages

🚀 Quick Start

Installation (3 Steps)

Usage Example

Configuration Location

🔧 Advanced Installation

Option 1: NPM Install (Recommended)

Option 2: Build from Source

Verify Installation

Uninstall

📖 Usage

Basic Workflow

Actions

start - Start a new workflow

submit - Submit stage results

confirm - Confirm and save (unified action)

answer - Answer clarification questions

approve - Approve current stage (SM stage only)

status - Query workflow status

📁 File Structure

Your Project

Session State File

🎨 Engine Configuration

PO & Architect Stages (Dynamic Engine Selection)

SM Stage (Claude Only)

Dev/Review/QA Stages (Codex Only)

🔄 Workflow Flow

🛠️ Development

Project Structure

Build

Development Mode

Test Locally

📚 Master Orchestrator Design

🤝 Integration with Codex MCP

⚙️ Configuration

Quality Thresholds

Artifact Filenames

🔍 Troubleshooting

Server not starting

Tool name error

Session not found

Scores not detected

Clarification workflow issues

📝 License

🙋 Support

Similar Packages

bmad-mcp-server

BMAD-MCP

🎯 What is BMAD-MCP?

🏗️ Architecture

📋 Workflow Stages

🚀 Quick Start

Installation (3 Steps)

Usage Example

Configuration Location

🔧 Advanced Installation

Option 1: NPM Install (Recommended)

Option 2: Build from Source

Verify Installation

Uninstall

📖 Usage

Basic Workflow

Actions

start - Start a new workflow

submit - Submit stage results

confirm - Confirm and save (unified action)

answer - Answer clarification questions

approve - Approve current stage (SM stage only)

status - Query workflow status

📁 File Structure

Your Project

Session State File

🎨 Engine Configuration

PO & Architect Stages (Dynamic Engine Selection)

SM Stage (Claude Only)

Dev/Review/QA Stages (Codex Only)

`start` - Start a new workflow

`submit` - Submit stage results

`confirm` - Confirm and save (unified action)

`answer` - Answer clarification questions

`approve` - Approve current stage (SM stage only)

`status` - Query workflow status

`start` - Start a new workflow

`submit` - Submit stage results

`confirm` - Confirm and save (unified action)

`answer` - Answer clarification questions

`approve` - Approve current stage (SM stage only)

`status` - Query workflow status