BMAD MCP Server

License: ISC

A Model Context Protocol server that brings the BMAD Method to AI assistants.

Features • Installation • Usage • Documentation

Overview

The BMAD MCP Server provides AI assistants with access to 11 specialized agents and 36+ automated workflows from the BMAD (Building Modern Apps Decisively) methodology. Configure once, use everywhere across all your projects.

What is BMAD?

BMAD is a comprehensive software development methodology with specialized AI agents for different roles (Business Analyst, Architect, Developer, UX Designer, etc.) and workflows for common tasks (PRD generation, architecture design, debugging, testing).

Why MCP?

Instead of copying BMAD files to every project, the MCP server provides universal access:

✅ Single installation serves all projects
✅ Consistent methodology everywhere
✅ No project clutter
✅ Easy updates

Features

Unified Tool Architecture

Single bmad tool with intelligent operations:

// List available agents and workflows
{ operation: "list", query: "agents" }

// Read agent details (no execution)
{ operation: "read", type: "agent", agent: "analyst" }

// Execute agent with context
{ operation: "execute", agent: "analyst", message: "Help me..." }

11 Specialized Agents

Agent	Role	Load with
📊 Mary	Business Analyst	`analyst`
🏗️ Winston	System Architect	`architect`
💻 Amelia	Developer	`dev`
🎨 Sally	UX Designer	`ux-designer`
🧪 Murat	Test Architect	`tea`
📋 John	Product Manager	`pm`
🔄 Bob	Scrum Master	`sm`
🐛 Diana	Debug Specialist	`debug`
...	[+3 more agents]

36+ Automated Workflows

prd              # Product Requirements Document
architecture     # System architecture design
debug-inspect    # Comprehensive debugging
atdd             # Acceptance test generation
ux-design        # UX specifications
party-mode       # Multi-agent brainstorming
... and 30+ more

MCP Capabilities

Tools - Unified bmad tool for all operations
Resources - Access BMAD files via bmad:// URIs
Prompts - Agents as native MCP prompts
Completions - Smart autocomplete for arguments
Multi-source - Project, user, and Git remote support

Installation

Prerequisites

Node.js 18 or later
An MCP-compatible client (Claude Desktop, VS Code with Copilot, Cline, etc.)

Quick Start

Option 1: npx (Recommended)

Add to your MCP client configuration:

{
  "mcpServers": {
    "bmad": {
      "command": "npx",
      "args": ["-y", "bmad-mcp-server"]
    }
  }
}

Option 2: Global Installation

npm install -g bmad-mcp-server

{
  "mcpServers": {
    "bmad": {
      "command": "bmad-mcp-server"
    }
  }
}

Option 3: Local Development

git clone https://github.com/mkellerman/bmad-mcp-server.git
cd bmad-mcp-server
npm install
npm run build

{
  "mcpServers": {
    "bmad": {
      "command": "node",
      "args": ["/absolute/path/to/bmad-mcp-server/build/index.js"]
    }
  }
}

Client-Specific Setup

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "bmad": {
      "command": "npx",
      "args": ["-y", "bmad-mcp-server"]
    }
  }
}

Restart Claude Desktop.

VS Code with GitHub Copilot

Install the latest GitHub Copilot extension
Open Settings (JSON)
Add to github.copilot.chat.mcp.servers:

{
  "github.copilot.chat.mcp.servers": {
    "bmad": {
      "command": "npx",
      "args": ["-y", "bmad-mcp-server"]
    }
  }
}

Restart VS Code

Cline (VS Code Extension)

Open Cline settings
Add MCP server:

{
  "mcpServers": {
    "bmad": {
      "command": "npx",
      "args": ["-y", "bmad-mcp-server"]
    }
  }
}

Usage

Natural Language Examples

Just ask your AI assistant naturally - it handles the MCP tool calls automatically:

Agent Execution:

You: "Ask Mary to analyze the market opportunity for a SaaS product"
→ AI executes: { operation: "execute", agent: "analyst", message: "..." }
→ Mary (Business Analyst) provides market analysis

Workflow Execution:

You: "Start a PRD workflow for a task management app"
→ AI executes: { operation: "execute", workflow: "prd", message: "..." }
→ John (Product Manager) guides you through PRD creation

Debug Assistance:

You: "Ask Diana to debug this script" (with code attached)
→ AI executes: { operation: "execute", agent: "debug", message: "..." }
→ Diana starts comprehensive debugging workflow

Collaborative Problem Solving:

You: "Start party-mode with the planning team to brainstorm features"
→ AI executes: { operation: "execute", workflow: "party-mode", message: "..." }
→ Multiple agents collaborate on brainstorming session

Architecture Review:

You: "Have Winston review this system design"
→ AI executes: { operation: "execute", agent: "architect", message: "..." }
→ Winston provides architectural guidance

Direct MCP Tool Usage

You can also work with the tool directly (useful for development/testing):

List available agents:

{
  "operation": "list",
  "query": "agents"
}

Execute an agent:

{
  "operation": "execute",
  "agent": "analyst",
  "message": "Help me analyze the market for a SaaS product"
}

Run a workflow:

{
  "operation": "execute",
  "workflow": "prd",
  "message": "Create PRD for task management app"
}

Read agent details:

{
  "operation": "read",
  "type": "agent",
  "agent": "architect"
}

Advanced Configuration

Multi-source loading with Git remotes:

{
  "mcpServers": {
    "bmad": {
      "command": "npx",
      "args": [
        "-y",
        "bmad-mcp-server",
        "git+https://github.com/org/custom-bmad.git#main"
      ]
    }
  }
}

Custom project root:

{
  "mcpServers": {
    "bmad": {
      "command": "npx",
      "args": ["-y", "bmad-mcp-server"],
      "env": {
        "BMAD_ROOT": "/custom/bmad/location"
      }
    }
  }
}

Resource Discovery Priority

The server searches for BMAD content in this order:

Project-local: ./bmad/ (highest priority - project customizations)
User-global: ~/.bmad/ (personal defaults)
Git remotes: Cloned to ~/.bmad/cache/git/ (shared/team content)
Package defaults: Built-in BMAD files (always available)

Documentation

Architecture - System design and components
API Contracts - MCP tools and TypeScript APIs
Development Guide - Contributing and testing
Release Process - Release workflow for maintainers

Development

Setup

# Clone repository
git clone https://github.com/mkellerman/bmad-mcp-server.git
cd bmad-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Project Structure

src/
├── index.ts              # MCP server entry point
├── cli.ts                # CLI entry point
├── server.ts             # MCP server implementation
├── core/
│   ├── bmad-engine.ts    # Core business logic
│   └── resource-loader.ts # Multi-source content loading
├── tools/
│   ├── bmad-unified.ts   # Unified tool implementation
│   └── operations/       # Operation handlers
├── types/                # TypeScript types
└── utils/                # Utilities

npm Scripts

npm run build          # Compile TypeScript
npm run dev            # Development mode with auto-restart
npm test               # Run all tests
npm run test:unit      # Unit tests only
npm run test:coverage  # Coverage report
npm run lint           # Check linting
npm run format         # Format code

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suite
npm run test:unit
npm run test:integration
npm run test:e2e

# Watch mode
npm run test:watch

Architecture

High-Level Overview

AI Assistant (Claude, Copilot, etc.)
         ↓ MCP Protocol
    MCP Server Layer
         ↓
    BMAD Engine (transport-agnostic)
         ↓
  Resource Loader (multi-source)
         ↓
   BMAD Content (agents, workflows)

Key Components

Server: MCP protocol implementation (tools, resources, prompts)
Engine: Transport-agnostic business logic
Loader: Multi-source content discovery and loading
Tools: Unified bmad tool with modular operations

See Architecture Documentation for details.

Contributing

We welcome contributions! Please see our Development Guide for:

Development setup
Code style guidelines
Testing requirements
Pull request process

Quick Contribution Guide

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Make your changes with tests
Run tests: npm test
Commit: git commit -m "feat: add my feature"
Push: git push origin feature/my-feature
Create a Pull Request

We use Conventional Commits for commit messages.

License

Credits

This MCP server is built on the BMAD Method. All methodology, agents, workflows, and best practices are credited to the original BMAD Method project.