Bmad MCP Server

🚀 BMAD-MCP

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

BMAD-MCP offers a comprehensive agile development workflow that spans from the Product Owner (PO) to Quality Assurance (QA). It features interactive requirements gathering, dynamic engine selection, a content reference system, and human-readable task names, ensuring an efficient and organized development process.

🚀 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 the 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 the BMAD workflow (PO stage)
2. Generate a Product Requirements Document (with interactive Q&A)
3. Generate a System Architecture (with interactive Q&A)
4. Create a Sprint Plan
5. Implement code (using Codex)
6. Perform a code review
7. Run quality assurance tests

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

Configuration Location

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

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

✨ Features

• Complete Agile Workflow: Manages the entire agile development process from PO to QA.
• Interactive Requirements Gathering: Asks clarifying questions to ensure complete requirements.
• Dynamic Engine Selection: Uses Claude by default and switches to a dual-engine approach when needed.
• Content Reference System: Efficiently uses tokens via file references.
• Human-Readable Task Names: Organizes tasks by name, not UUID.

📦 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 the 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 the npm package
npm uninstall -g bmad-mcp

💻 Usage Examples

Basic Usage

// 1. Start the workflow
const startResult = await callTool("bmad-task", {
  action: "start",
  cwd: "/path/to/your/project",
  objective: "Implement a 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 the next stage)
await callTool("bmad-task", {
  action: "confirm",
  session_id: session_id,
  confirmed: true
});

Advanced Usage

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 workflow has started**...",
  "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 generation completed**\nQuality score: 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": "⚠️ **Requirement clarification...**",
  "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 the next stage):

{
  "session_id": "uuid",
  "stage": "architect",
  "state": "generating",
  "requires_user_confirmation": true,
  "interaction_type": "awaiting_generation",
  "user_message": "💾 **Document saved and moved to the next stage**...",
  "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": "📝 **Your answers have been received**...",
  "role_prompt": "<updated prompt with user answers>",
  "engines": ["claude"],
  "pending_user_actions": ["regenerate_with_answers"]
}

approve - Approve the current stage (SM stage only)

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

Returns (when entering the Dev stage):

{
  "session_id": "uuid",
  "stage": "dev",
  "state": "generating",
  "requires_user_confirmation": true,
  "interaction_type": "awaiting_generation",
  "user_message": "✅ **Sprint Plan approved**\n\nMoving to the next stage: Developer - Implementation\n\nThe Sprint Plan includes 3 Sprints:\n1. Sprint 1: Infrastructure\n2. Sprint 2: Core features\n3. Sprint 3: Optimization and refinement\n\n⚠️ Important: Please specify the development scope...",
  "role_prompt": "<dev prompt>",
  "engines": ["codex"],
  "pending_user_actions": ["specify_sprint_scope_then_generate"]
}

Important - Dev Stage Behavior:

• After approving the Sprint Plan, the workflow enters the Dev stage but does NOT auto-start development.
• The user must explicitly specify the development scope:
  • "Start development" → Implements ALL sprints (default).
  • "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": [...]
}

📚 Documentation

What is BMAD-MCP?

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

• Manages workflow state: Keeps track of which stage you're in and what's needed next.
• Dispatches role prompts: Provides detailed prompts for each role.
• Saves artifacts: Stores PRDs, architectures, code, and 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 the next stage

Workflow Stages

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 the objective contains "codex" or "使用 codex".
• If the dual engine is enabled:
  • Calls both Claude and Codex.
  • Each generates an independent solution.
  • BMAD-MCP merges the results:
    • If both ≥ 90: choose the higher score.
    • If one ≥ 90: choose that one.
    • If both < 90: choose the higher score and refine.
• Interactive Clarification:
  • First iteration: Identify gaps and generate 3 - 5 clarification questions.
  • The user answers the questions.
  • Regenerate based on the answers.
  • Iterate until the 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 are in one place.
• Workflow definition: Clear stage sequence.
• Engine configuration: Specifies which engines to use for each stage.
• Quality gates: Defines score thresholds and approval points.

Integration with Codex MCP

When calling Codex for the 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.
• The Claude Code configuration should use bmad-task as the tool name.

Session not found

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

Scores not detected

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

Clarification workflow issues

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

🔧 Technical Details

• BMAD-MCP manages the agile development workflow by tracking the state of each stage and dispatching appropriate role prompts.
• It uses a content reference system to efficiently manage tokens, especially when dealing with large artifacts.
• The dynamic engine selection mechanism ensures that the most appropriate engines are used for each stage, optimizing the quality of the output.

📄 License

This project is licensed under the MIT License.

🙋 Support

• Documentation: Refer to this README.
• Issues: Report any issues on GitHub.
• Reference: Visit https://github.com/cexll/myclaude.

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