Works within Git repositories to manage agile development workflows and save artifacts in project directories
References GitHub repository for source code and installation instructions
Uses Mermaid diagrams to visualize the workflow process and stage transitions in the documentation
Distributed as an npm package for global installation and integration with Claude Code's MCP server configuration
Built with TypeScript and provides TypeScript examples for integration usage
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
📋 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)
That's it! Restart Claude Code and you're ready to use BMAD workflow.
Usage Example
Simply tell Claude Code to use BMAD:
Configuration Location
MCP configuration is automatically added to ~/.claude/config.json
:
🔧 Advanced Installation
Option 1: NPM Install (Recommended)
Option 2: Build from Source
Verify Installation
Uninstall
📖 Usage
Basic Workflow
Actions
start
- Start a new workflow
Returns:
submit
- Submit stage results
Returns (if score >= 90):
Returns (if score < 90 with clarification questions):
confirm
- Confirm and save (unified action)
Returns (saves artifact + advances to next stage):
answer
- Answer clarification questions
Returns:
approve
- Approve current stage (SM stage only)
Returns (when entering Dev stage):
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
Returns:
📁 File Structure
Your Project
Session State File
🎨 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
🛠️ Development
Project Structure
Build
Development Mode
Test Locally
📚 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:
⚙️ Configuration
Quality Thresholds
Defined in master-prompt.ts
:
Artifact Filenames
🔍 Troubleshooting
Server not starting
Tool name error
Important: The tool name is
bmad-task
, notbmad
Use
callTool("bmad-task", {...})
in your codeClaude Code configuration should use
bmad-task
as the tool name
Session not found
Ensure
.bmad-task/
directory has write permissionsCheck
session_id
is correctVerify
cwd
path is absolute
Scores not detected
Ensure generated content includes:
Quality Score: X/100
or"quality_score": 92
in JSONCheck 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 viaanswer
actionDo 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.
local-only server
The server can only run on the client's local machine because it depends on local resources.
Tools
Orchestrates complete agile development workflows from product requirements to QA testing through role-based stages (PO → Architect → SM → Dev → Review → QA). Manages workflow state, generates role-specific prompts, and saves artifacts while integrating with multiple AI engines for comprehensive project delivery.