BMAD MCP Server

BMAD MCP Server

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

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

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

{
  "github.copilot.chat.mcp.servers": {
    "bmad": {
      "command": "npx",
      "args": ["-y", "bmad-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:

1. Project-local: ./bmad/ (highest priority - project customizations)
2. User-global: ~/.bmad/ (personal defaults)
3. Git remotes: Cloned to ~/.bmad/cache/git/ (shared/team content)
4. 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

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

We use Conventional Commits for commit messages.

License

ISC © mkellerman

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.

Links

• Repository: https://github.com/mkellerman/bmad-mcp-server
• Issues: https://github.com/mkellerman/bmad-mcp-server/issues
• npm Package: https://www.npmjs.com/package/bmad-mcp-server
• BMAD Method: https://github.com/bmad-code-org/BMAD-METHOD
• MCP Specification: https://modelcontextprotocol.io/