BMAD MCP Server

A Model Context Protocol (MCP) server that bridges BMAD (Breakthrough Method of Agile AI-driven Development) agents with GitHub Copilot, enabling AI-assisted development workflows through specialized agent tools and prompts.

What is BMAD?

BMAD is a comprehensive AI-driven development methodology featuring specialized agents for different aspects of software development, including:

• Core Agents: Master orchestration and task execution
• Builder Module: Agent and workflow creation/maintenance
• Game Development: Specialized game development agents
• Methodology Module: Full software development lifecycle agents
• Creative Innovation: Design thinking and creative problem-solving

Prerequisites

• Node.js 20.0.0 or higher
• VS Code with GitHub Copilot extension
• BMAD Repository cloned locally
• MCP Support in VS Code (available in recent versions)

Quick Start

1. Clone and Setup BMAD Repository

git clone https://github.com/bmad-code-org/BMAD-METHOD.git
cd BMAD-METHOD
npm install

2. Build the MCP Server

cd mcp-server
npm install
npm run build

3. Configure VS Code

Add the following to your VS Code settings.json (accessible via Cmd/Ctrl + Shift + P → "Preferences: Open Settings (JSON)"):

{
  "mcp.servers": {
    "bmad": {
      "command": "node",
      "args": [
        "/absolute/path/to/BMAD-MCP-Server/mcp-server/build/index.js"
      ],
      "env": {
        "BMAD_PROJECT_ROOT": "/absolute/path/to/BMAD-METHOD"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Important:

• Replace /absolute/path/to/BMAD-MCP-Server with the path to this MCP server repository
• Set BMAD_PROJECT_ROOT environment variable to point to your BMAD repository
• If not set, it defaults to looking in the parent directory

4. Reload VS Code

Use Cmd/Ctrl + Shift + P → "Developer: Reload Window" to apply the configuration.

5. Verify Installation

Open GitHub Copilot Chat and ask:

"What tools are available from the bmad server?"

You should see a list of 50+ BMAD agent tools.

Available Tools

Core Agents

• bmad_master_list_tasks - List available tasks
• bmad_master_list_workflows - List available workflows
• bmad_master_party_mode - Group chat with all agents
• bmad_orchestrator_* - Orchestration and agent management tools

Builder Tools

• bmad_builder_create_agent - Create new BMAD agents
• bmad_builder_edit_agent - Edit existing agents
• bmad_builder_validate_workflow - Validate workflows

Development Tools

• architect_create_architecture - Create architecture documents
• architect_create_excalidraw_diagram - Generate system diagrams
• dev_* - Development workflow tools
• analyst_* - Analysis and requirements tools

Game Development

• game_architect_* - Game architecture tools
• game_designer_* - Game design tools
• game_dev_* - Game development tools

Creative & Innovation

• brainstorming_coach_* - Creative ideation tools
• design_thinking_coach_* - Design thinking facilitation
• innovation_strategist_* - Innovation planning tools

Available Prompts

Load agent personas as system prompts:

• bmad_master - Master task executor and workflow orchestrator
• architect - System architect and technical design leader
• game_designer - Game design specialist
• analyst - Requirements and data analysis expert
• dev - Software development engineer
• And 15+ more specialized agent prompts

Usage Examples

Using Tools

"Run the architect_create_architecture tool to create an architecture document"
"Use the bmad_master_list_tasks tool"
"Execute architect implementation readiness check"

Loading Prompts

"Load the architect prompt and help me design a microservices architecture"
"Use the game_designer persona to review my game concept"
"Load bmad_master and show me available workflows"

Interactive Workflow

1. "Load the architect prompt"
2. "Create an architecture document for my e-commerce platform"
3. "Run the architect_create_excalidraw_diagram tool"
4. "Validate the architecture with architect_validate_architecture"

Troubleshooting

Server Not Connecting

1. Check Path: Ensure the path in settings.json is correct and absolute
2. Build Status: Verify npm run build completed successfully
3. Node Version: Ensure Node.js 20+ is installed
4. VS Code Version: Update to latest VS Code with MCP support

Tools Not Appearing

1. Reload Window: Use "Developer: Reload Window"
2. Restart VS Code: Completely close and reopen
3. Check Output: Look for MCP errors in VS Code's Output panel
4. Verify Configuration: Ensure JSON syntax is valid in settings.json

Permission Issues

• Ensure the MCP server has read access to the BMAD repository
• Check that Node.js can execute the built index.js file

Development Mode

For development and debugging:

npm run dev  # Runs with ts-node for live reloading

Architecture

The MCP server:

• Scans all *.agent.yaml and *.agent.xml files in the BMAD repository
• Parses agent definitions and their menu items
• Exposes menu triggers as MCP tools
• Provides agent personas as MCP prompts
• Executes BMAD workflows and actions through the tool interface

Contributing

1. Agent definitions are in src/core/agents/ and src/modules/*/agents/
2. Add new menu items to agent YAML files to create new tools
3. Update agent personas to modify prompt behavior
4. Test changes by rebuilding and reloading VS Code

License

MIT License - See BMAD repository LICENSE file.

Support

• Issues: Report bugs in the BMAD repository
• Documentation: See main BMAD docs for agent capabilities
• Community: Join BMAD discussions for best practices