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
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)
# 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:
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:
{
"mcpServers": {
"bmad": {
"type": "stdio",
"command": "bmad-mcp"
}
}
}
🔧 Advanced Installation
Option 1: NPM Install (Recommended)
npm install -g bmad-mcp
claude mcp add-json --scope user bmad '{"type":"stdio","command":"bmad-mcp"}'
Option 2: Build from Source
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
# 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
# Remove from Claude Code
claude mcp remove bmad
# Uninstall npm package
npm uninstall -g bmad-mcp
📖 Usage
Basic Workflow
// 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
{
"action": "start",
"cwd": "/path/to/project",
"objective": "Project description"
}
Returns:
{
"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
{
"action": "submit",
"session_id": "uuid",
"stage": "po",
"claude_result": "...",
"codex_result": "..."
}
Returns (if score >= 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"]
}
Returns (if score < 90 with clarification questions):
{
"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)
{
"action": "confirm",
"session_id": "uuid",
"confirmed": true
}
Returns (saves artifact + advances to next stage):
{
"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
{
"action": "answer",
"session_id": "uuid",
"answers": {
"q1": "Target users are enterprise B2B customers",
"q2": "Expected 10k concurrent users with <200ms response time"
}
}
Returns:
{
"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)
{
"action": "approve",
"session_id": "uuid",
"approved": true
}
Returns (when entering Dev stage):
{
"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
{
"action": "status",
"session_id": "uuid"
}
Returns:
{
"session_id": "uuid",
"current_stage": "dev",
"current_state": "generating",
"stages": {...},
"artifacts": [...]
}
📁 File Structure
Your Project
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
{
"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
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
bmad-mcp/
├── src/
│ ├── index.ts # Main MCP server
│ └── master-prompt.ts # All role prompts
├── dist/ # Compiled output
├── package.json
├── tsconfig.json
└── README.md
Build
npm run build
Development Mode
npm run dev # Watch mode
Test Locally
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:
// 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:
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
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
# Check installation
which bmad-mcp
# Test directly
bmad-mcp
Tool name error
- Important: The tool name is
bmad-task, notbmad - Use
callTool("bmad-task", {...})in your code - Claude Code configuration should use
bmad-taskas the tool name
Session not found
- Ensure
.bmad-task/directory has write permissions - Check
session_idis correct - Verify
cwdpath is absolute
Scores not detected
- Ensure generated content includes:
Quality Score: X/100or"quality_score": 92in 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 viaansweraction - Do NOT auto-generate answers - wait for real user input
- Check
requires_user_confirmation: truebefore 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.