Skip to main content
Glama

BMAD-MCP

by cexll

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, 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


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

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/cexll/bmad-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server