Dali1789/bmad-mcp-server

BMAD MCP Server 🚀

A comprehensive Model Context Protocol (MCP) server implementing the BMAD (Business Modeling and Development) methodology. Provides intelligent task management, multi-agent workflows, and cross-IDE project management through the MCP protocol.

✨ Features

🤖 6 Specialized AI Agents

• 📊 Analyst: Business analysis, market research, requirement gathering
• 🏗️ Architect: System design, architecture planning, tech stack selection
• 💻 Developer: Code implementation, debugging, technical development
• 📋 Project Manager: Task coordination, timeline management, resource planning
• 🔍 QA: Quality assurance, testing strategies, code review
• 🔍 Coder Agent: Advanced semantic code analysis and editing capabilities ⭐ NEW!

📋 Advanced Task Management

• Real-time Progress Tracking: Live updates and notifications
• Intelligent Scheduling: Auto-allocation with capacity management
• Follow-up Task Generation: Automatic workflow progression
• Notion Integration: Bi-directional sync with Notion databases
• TodoWrite Bridge: Seamless Claude integration

⏱️ Time & Cost Tracking ⭐ NEW!

• Precise Time Tracking: Exact time spent on each project with session management
• AI Cost Calculation: Automatic calculation of AI model costs per project
• Project Billing: Comprehensive billing reports for client invoicing
• Multi-format Export: JSON, CSV, and invoice-style billing reports
• Cost Optimization: Track and optimize AI model usage across projects
• Session Management: Auto-end stale sessions and track work patterns

🎨 Template-System & Standardisierte Projektstrukturen ⭐ NEW!

• 6 Projekt-Templates: standard, web-app, api, mobile, data-science, infrastructure
• Automatische Struktur-Erstellung: Einheitliche .bmad-core/ Verzeichnisse
• Auto-Discovery: Erkennt automatisch neue BMAD-Projekte
• Migration-Tools: Migriert bestehende Projekte auf BMAD v2.0 Standard
• Zero-Setup: Neue Projekte sind sofort produktiv mit kompletter Konfiguration

🔄 Enhanced Features

• BMAD-METHOD Workflow System: Complete implementation with intelligent orchestration ⭐ NEW!
• Quality Gates (@qa commands): 6 comprehensive quality assurance commands ⭐ NEW!
• Advanced Semantic Code Analysis: Professional code intelligence via Coder Agent ⭐ NEW!
• Time-based Monitoring: Scheduled reminders and progress checks
• Work Day Simulation: Demo modes and realistic progression testing
• Live Console Output: Beautiful formatted status displays
• Project Context Integration: Multi-project support with global registry
• Performance Metrics: Detailed tracking and reporting

🌐 Universal IDE Access

Compatible with any IDE supporting MCP:

• Claude Code ✅
• VS Code ✅
• Cursor ✅
• Any MCP-compatible IDE ✅

🚀 Quick Start

Prerequisites

• Python 3.8+
• OpenRouter API Key (for AI model routing)
• Notion API Token (optional, for database sync)

Installation

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

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

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your API keys

Configuration

Add to your IDE's MCP configuration:

Claude Code (claude_desktop_config.json)

{
  "mcpServers": {
    "bmad": {
      "command": "python",
      "args": ["-m", "src.bmad_mcp.server"],
      "cwd": "/path/to/bmad-mcp-server",
      "env": {
        "PYTHONPATH": "/path/to/bmad-mcp-server",
        "OPENROUTER_API_KEY": "your_openrouter_api_key",
        "NOTION_TOKEN": "your_notion_token"
      }
    }
  }
}

VS Code / Cursor

{
  "mcp.servers": {
    "bmad": {
      "command": "python",
      "args": ["-m", "src.bmad_mcp.server"],
      "cwd": "/path/to/bmad-mcp-server",
      "env": {
        "PYTHONPATH": "/path/to/bmad-mcp-server",
        "OPENROUTER_API_KEY": "your_openrouter_api_key"
      }
    }
  }
}

🛠️ Available MCP Tools

🤖 Agent Management

📋 Task Management

⏱️ Time & Cost Tracking ⭐ NEW!

⚡ Enhanced Features

🔧 Project Management

🚀 BMAD-METHOD Workflow System ⭐ NEW!

🔍 Semantic Code Analysis ⭐ NEW!

🎨 Template-System ⭐ NEW!

📊 Usage Examples

Basic Task Management

# List available agents
bmad_list_agents()

# Activate developer agent
bmad_activate_agent(agent="dev")

# Create a new task
bmad_create_task(
    task_id="feature-implementation",
    name="Implement user authentication",
    allocated_hours=8.0,
    agent="dev"
)

# Update progress
bmad_update_task_progress(
    task_id="feature-implementation", 
    hours_completed=2.5
)

# Get daily overview
bmad_get_today_tasks()

Real-time Monitoring

# Start live monitoring
bmad_start_realtime_mode()

# Begin work session
bmad_start_work_session(task_id="feature-implementation")

# Work on task...

# End session with automatic progress logging
bmad_end_work_session(
    task_id="feature-implementation",
    hours_worked=2.0
)

# Get comprehensive status
bmad_get_realtime_status()

Time & Cost Tracking ⭐ NEW!

# Start time tracking for a task
bmad_start_timer(
    task_id="feature-implementation",
    agent="dev",
    session_type="development",
    description="Implementing user authentication system"
)

# Stop timer with AI cost calculation
bmad_stop_timer(
    task_id="feature-implementation",
    ai_model_used="claude-sonnet-4",
    tokens_input=1500,
    tokens_output=800,
    mark_completed=False
)

# Get task time summary
bmad_get_task_time_summary(task_id="feature-implementation")

# Generate project billing report
bmad_get_project_billing(
    project_id="my-project-id",
    start_date="2025-01-01",
    end_date="2025-01-31",
    export_format="invoice"  # json, csv, or invoice
)

# Get daily tracking report
bmad_get_daily_time_report(date="2025-01-20")

# Auto-end stale sessions (running >8 hours)
bmad_auto_end_stale_sessions(max_hours=8)

Project Context

# Detect BMAD project
bmad_detect_project(path="./my-project")

# Register in global registry
bmad_register_project(
    project_path="./my-project",
    project_name="My Awesome Project"
)

# Get project overview
bmad_get_project_status()

Template-System Usage ⭐ NEW!

# List available templates
bmad_list_project_templates()

# Get template details
bmad_get_project_template_info(template_name="web-app")

# Create new project with template
bmad_create_project(
    project_path="./my-web-app",
    template="web-app",
    name="My Web Application",
    description="Modern React-based web application"
)

# Migrate existing project
bmad_migrate_project_to_standard(
    project_path="./legacy-project",
    backup=True
)

Available Templates

• standard: Basic BMAD project with full structure
• web-app: Frontend/Backend with React/Vue/Angular support
• api: REST/GraphQL APIs with OpenAPI documentation
• mobile: React Native/Flutter cross-platform apps
• data-science: ML/Jupyter with notebooks and data pipelines
• infrastructure: Docker/Terraform/Kubernetes deployments

Simulation & Testing

# Simulate full work day
bmad_simulate_work_day(speed_factor=10.0)

# Test specific agent workflow
bmad_simulate_agent_workday(agent="qa", hours=6.0)

# Simulate crisis scenarios
bmad_simulate_crisis_scenario(crisis_type="blocked_task")

Advanced Time Tracking Workflows ⭐ NEW!

# Start comprehensive work session
bmad_start_timer(
    task_id="user-auth-system",
    agent="dev",
    session_type="development",
    description="Implementing OAuth2 integration"
)

# Work on task with AI assistance
# ... development work with AI model usage ...

# Stop timer with detailed AI cost tracking
bmad_stop_timer(
    task_id="user-auth-system",
    ai_model_used="claude-sonnet-4",
    tokens_input=2500,
    tokens_output=1200,
    mark_completed=True
)

# Generate comprehensive project billing
billing_report = bmad_get_project_billing(
    project_id="client-project-2025",
    start_date="2025-01-01",
    end_date="2025-01-31",
    export_format="invoice"
)

# Monitor daily productivity
daily_report = bmad_get_daily_time_report("2025-01-20")
print(f"Today: {daily_report['total_hours']:.2f}h, ${daily_report['total_cost_usd']:.2f}")

# Automatic session management
bmad_auto_end_stale_sessions(max_hours=6)  # End sessions > 6 hours

🏗️ Architecture

bmad-mcp-server/
├── src/
│   └── bmad_mcp/
│       ├── core/                    # Core functionality
│       │   ├── task_tracker.py      # Advanced task management
│       │   ├── time_cost_tracker.py # Time & cost tracking ⭐ NEW!
│       │   ├── console_formatter.py # Live output formatting  
│       │   ├── realtime_updater.py  # Real-time monitoring
│       │   ├── time_monitor.py      # Scheduled monitoring
│       │   ├── simulator.py         # Demo & testing
│       │   ├── notion_sync.py       # Notion integration
│       │   └── global_registry.py   # Cross-IDE projects
│       ├── agents/                  # Agent definitions
│       │   ├── analyst.py           # Business analysis
│       │   ├── architect.py         # System design
│       │   ├── developer.py         # Code implementation
│       │   ├── project_manager.py   # Project coordination
│       │   ├── qa.py               # Quality assurance
│       │   └── coder.py           # Advanced semantic code analysis and editing
│       ├── workflows/              # BMAD-METHOD workflow system
│       │   ├── workflow_engine.py  # Central workflow orchestration
│       │   ├── orchestrator_agent.py # Project/Story lifecycle management
│       │   ├── quality_gates.py    # Quality assurance (@qa commands)
│       │   └── workflow_states.py  # State machine definitions
│       ├── tools/                   # MCP tool implementations
│       ├── routing/                 # OpenRouter integration
│       └── server.py               # MCP server
├── config/                         # Configuration templates
├── docs/                          # Documentation
├── examples/                      # Usage examples
└── tests/                        # Test suite

🔧 Configuration

Environment Variables

# Required
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Optional  
NOTION_TOKEN=your_notion_integration_token
BMAD_MAX_DAILY_HOURS=10
BMAD_DEFAULT_AGENT=dev
BMAD_LOG_LEVEL=INFO

Agent Configuration

Each agent can be customized via configuration files:

# config/bmad-global-config.yaml
agents:
  dev:
    model: "anthropic/claude-3.5-sonnet"
    temperature: 0.1
    max_tokens: 4000
  architect:
    model: "anthropic/claude-3-opus"
    temperature: 0.3
    max_tokens: 8000

🐳 Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# Environment variables via .env file
cp .env.example .env
# Edit .env file with your API keys
docker-compose up -d

🧪 Testing

# Run test suite
python -m pytest tests/

# Run specific test category
python -m pytest tests/test_task_management.py

# Run with coverage
python -m pytest --cov=src/bmad_mcp tests/

📚 Documentation

• - Complete workflow implementation guide ⭐ NEW!
• - Complete tool documentation
• - Working with specialized agents
• - Advanced task workflows
• - @qa commands and quality assurance ⭐ NEW!
• - LSP-based code intelligence ⭐ NEW!
• - BMAD project configuration
• - IDE setup instructions
• - Common issues and solutions

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See for detailed guidelines.

📈 Roadmap

✅ Recently Completed (v2.1)

• Time & Cost Tracking System: Precise project billing with AI cost calculation ⭐ NEW!
• BMAD-METHOD Workflow System: Complete workflow implementation with intelligent orchestration
• Quality Gates System: All 6 @qa commands (*risk, *design, *trace, *nfr, *review, *gate)
• Serena Bridge Agent: LSP-based semantic code intelligence integration
• Agent Coordination: 6-agent ecosystem with smart routing and collaboration
• Template-System: 6 standardized project templates
• Auto-Discovery: Automatic project detection and integration
• Migration Tools: Legacy project migration to BMAD v2.0
• Standardized Structure: Unified .bmad-core/ project layout

🔄 In Progress (v2.2)

• Workflow Automation: Advanced automation rules and triggers
• Multi-Project Workflows: Cross-project dependency management
• Enhanced Analytics: Workflow performance insights and optimization
• Custom Quality Gates: User-definable quality criteria and checks

🚀 Planned Features (v3.0)

• Web Dashboard: Browser-based workflow management interface
• Team Collaboration: Multi-user project support with role-based access
• Enterprise Workflows: Advanced enterprise features and compliance
• Serena Enhancements: Multi-language LSP support and AI-assisted refactoring
• Plugin System: Custom agent and quality gate development
• Mobile App: Companion mobile application for workflow monitoring
• Template Marketplace: Community-driven template sharing platform

🔐 Security

• All API keys managed via environment variables
• No secrets stored in code or configuration files
• Secure MCP protocol communication
• Optional token rotation and audit logging

See for security guidelines.

📝 License

This project is licensed under the MIT License - see the file for details.

💬 Support

• Documentation:
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🙏 Acknowledgments

• Model Context Protocol - For the excellent MCP specification
• OpenRouter - For multi-model API access
• Notion - For database integration capabilities

Made with ❤️ for developers who love intelligent task management