bmad

The BMAD MCP Server implements the BMAD methodology within the Model Context Protocol (MCP) framework, exposing a suite of specialized AI agents and a comprehensive task management ecosystem. You can interact with six agents (Analyst, Architect, Developer, Project Manager, QA, and Coder) to perform business analysis, system design, coding tasks, task coordination, quality assurance, and advanced code analysis. The server also provides time and cost tracking, template-based project structures, Notion integration, and a live/workflow orchestration layer via the BMAD-METHOD workflow system. To use it, configure your MCP client to point at the Python-based MCP server entry point and provide necessary API tokens for OpenRouter and Notion if you want database syncing and advanced AI routing. The available tools span agent management, extensive task operations, time tracking, billing, Notion sync, and workflow automation, enabling multi-agent collaboration across projects and IDEs.

Prerequisites:

• Python 3.8+
• pip (comes with Python)
• Access to an environment where you can install dependencies (virtualenv is recommended)

Step-by-step installation:

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

# 2. Create and activate a virtual environment (optional but recommended)
python -m venv venv
# On Windows
venv\Scripts\activate.bat
# On macOS/Linux
source venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Set up environment Variables
# Copy example env file if present and edit as needed
cp .env.example .env
# Edit .env with your API keys (OPENROUTER_API_KEY, NOTION_TOKEN, etc.)

Configuration (example):

# Ensure your working directory is the project root
export PYTHONPATH=$(pwd)
export OPENROUTER_API_KEY=your_openrouter_api_key
export NOTION_TOKEN=your_notion_token  # optional

# Run the server (from project root)
python -m src.bmad_mcp.server

Notes:

• If you use a virtual environment, activate it before installing and running.
• The server expects certain environment variables for external services; set them in your shell or a .env file and load it as part of your startup script.

Tips and common issues:

• Ensure Python 3.8+ is installed and available in your PATH.
• If the server cannot locate modules, verify PYTHONPATH points to the repository root.
• Notion integration is optional; provide NOTION_TOKEN only if you plan to sync with Notion databases.
• For IDE integration, update the MCP configuration in your IDE (Claude Code, VS Code, Cursor, etc.) to reference the Python module path and include PYTHONPATH and API keys.
• If you upgrade BMAD components, re-run dependency installation to ensure compatibility.
• Monitor logs for agent initialization messages and task lifecycle events to troubleshoot onboarding or synchronization issues.