Bmad MCP Server

🚀 BMAD-MCP

Business-Minded Agile Development ワークフローを MCP (Model Context Protocol) サーバーとしてオーケストレートします。

完全なアジャイル開発ワークフロー: PO → アーキテクト → SM → 開発者 → レビュー → QA

• 対話型要件収集 - 完全な要件を確保するために明確化の質問を行います。
• 動的エンジン選択 - デフォルトで Claude を使用し、必要に応じてデュアルエンジンを使用します。
• コンテンツ参照システム - ファイル参照による効率的なトークン使用。
• 人間が読みやすいタスク名 - UUID ではなくタスク名で整理します。

🚀 クイックスタート

インストール (3 ステップ)

# ステップ 1: npm からグローバルにインストール
npm install -g bmad-mcp

# ステップ 2: Claude Code に追加
claude mcp add-json --scope user bmad '{"type":"stdio","command":"bmad-mcp"}'

# ステップ 3: インストールを確認
bmad-mcp
# 期待される出力: "BMAD MCP Server running on stdio"

以上です！Claude Code を再起動すると、BMAD ワークフローを使用できます。

使用例

Claude Code に BMAD を使用するように指示するだけです。

ユーザー: bmad-task を使用してユーザー認証システムを作成する

Claude Code は以下のことを行います:
1. BMAD ワークフローを開始する (PO 段階)
2. 製品要件文書を生成する (対話型の質問と回答を伴う)
3. システムアーキテクチャを生成する (対話型の質問と回答を伴う)
4. スプリントプランを作成する
5. コードを実装する (Codex を使用)
6. コードレビューを行う
7. 品質保証テストを実行する

すべての成果物は以下に保存されます: .claude/specs/user-authentication-system/

設定場所

MCP 設定は自動的に ~/.claude/config.json に追加されます。

{
  "mcpServers": {
    "bmad": {
      "type": "stdio",
      "command": "bmad-mcp"
    }
  }
}

✨ 主な機能

BMAD-MCP は、軽量なワークフローオーケストレーターであり、完全なアジャイル開発プロセスを管理します。具体的には以下のことを行います。

• ワークフローの状態を管理 (どの段階にいるか、次に必要なものは何か)
• 役割プロンプトを送信 (各役割に対する詳細なプロンプトを提供)
• 成果物を保存 (PRD、アーキテクチャ、コード、レポート)
• LLM を呼び出さない (それは Claude Code の仕事)

🏗️ アーキテクチャ

ユーザー → Claude Code → bmad-mcp ツール
                       ↓
            返却内容: {
              stage: "po",
              role_prompt: "<完全な PO プロンプト>",
              engines: ["claude", "codex"],
              context: {...}
            }
                       ↓
Claude Code が実行:
  - Claude を呼び出す (役割プロンプト付き)
  - Codex MCP を呼び出す (役割プロンプト付き)
                       ↓
Claude Code が結果を送信 → bmad-mcp
                       ↓
bmad-mcp: マージ、スコア付け、保存、次の段階に進む

📋 ワークフローの段階

🔧 高度なインストール

オプション 1: NPM インストール (推奨)

npm install -g bmad-mcp
claude mcp add-json --scope user bmad '{"type":"stdio","command":"bmad-mcp"}'

オプション 2: ソースからビルド

git clone https://github.com/cexll/bmad-mcp-server
cd bmad-mcp-server
npm install
npm run build
npm link  # bmad-mcp をグローバルに使用可能にする

# Claude Code に追加
claude mcp add-json --scope user bmad '{"type":"stdio","command":"bmad-mcp"}'

インストールの確認

# バイナリが利用可能か確認
which bmad-mcp
# 出力: /usr/local/bin/bmad-mcp (または同等のもの)

# サーバーを直接テスト
bmad-mcp
# 期待される出力: "BMAD MCP Server running on stdio"
# Ctrl+C で終了

# 設定を読み込むために Claude Code を再起動

アンインストール

# Claude Code から削除
claude mcp remove bmad

# npm パッケージをアンインストール
npm uninstall -g bmad-mcp

📖 使い方

基本的なワークフロー

// 1. ワークフローを開始
const startResult = await callTool("bmad-task", {
  action: "start",
  cwd: "/path/to/your/project",
  objective: "ユーザーログインシステムを実装する"
});

const { session_id, task_name, role_prompt, engines } = JSON.parse(startResult.content[0].text);

// 2. エンジンで実行
if (engines.includes("claude")) {
  const claudeResult = await callClaude(role_prompt);
}
if (engines.includes("codex")) {
  const codexResult = await callCodexMCP(role_prompt);
}

// 3. 結果を送信
await callTool("bmad-task", {
  action: "submit",
  session_id: session_id,
  stage: "po",
  claude_result: claudeResult,
  codex_result: codexResult
});

// 4. 確認して進む (統合: 保存 + 次の段階に進む)
await callTool("bmad-task", {
  action: "confirm",
  session_id: session_id,
  confirmed: true
});

アクション

start - 新しいワークフローを開始

{
  "action": "start",
  "cwd": "/path/to/project",
  "objective": "プロジェクトの説明"
}

返却内容:

{
  "session_id": "uuid",
  "task_name": "project-description",
  "stage": "po",
  "state": "generating",
  "stage_description": "プロダクトオーナー - 要件分析",
  "requires_user_confirmation": true,
  "interaction_type": "awaiting_generation",
  "user_message": "📋 **BMAD ワークフローが開始されました**...",
  "role_prompt": "<完全なプロンプト>",
  "engines": ["claude"],
  "context": {...},
  "pending_user_actions": ["review_and_confirm_generation"]
}

submit - 段階の結果を送信

{
  "action": "submit",
  "session_id": "uuid",
  "stage": "po",
  "claude_result": "...",
  "codex_result": "..."
}

返却内容 (スコア >= 90 の場合):

{
  "session_id": "uuid",
  "stage": "po",
  "state": "awaiting_confirmation",
  "score": 92,
  "requires_user_confirmation": true,
  "interaction_type": "user_decision",
  "user_message": "✅ **PRD 生成が完了しました**\n品質スコア: 92/100...",
  "final_draft_summary": "...",
  "final_draft_file": ".bmad-task/temp/uuid/po_final_result_xxx.md",
  "pending_user_actions": ["confirm", "reject_and_refine"]
}

返却内容 (スコア < 90 で明確化の質問がある場合):

{
  "session_id": "uuid",
  "stage": "po",
  "state": "clarifying",
  "current_score": 75,
  "requires_user_confirmation": true,
  "interaction_type": "user_decision",
  "user_message": "⚠️ **要件の明確化...**",
  "gaps": ["ターゲットユーザーグループが不明", "..."],
  "questions": [{"id": "q1", "question": "...", "context": "..."}],
  "pending_user_actions": ["answer_questions"]
}

confirm - 確認して保存 (統合アクション)

{
  "action": "confirm",
  "session_id": "uuid",
  "confirmed": true
}

返却内容 (成果物を保存 + 次の段階に進む):

{
  "session_id": "uuid",
  "stage": "architect",
  "state": "generating",
  "requires_user_confirmation": true,
  "interaction_type": "awaiting_generation",
  "user_message": "💾 **ドキュメントが保存され、次の段階に進みました**...",
  "role_prompt": "<アーキテクトプロンプト>",
  "engines": ["claude"],
  "previous_artifact": ".claude/specs/task-name/01-product-requirements.md",
  "pending_user_actions": ["review_and_confirm_generation"]
}

answer - 明確化の質問に回答

{
  "action": "answer",
  "session_id": "uuid",
  "answers": {
    "q1": "ターゲットユーザーはエンタープライズ B2B 顧客です",
    "q2": "同時接続ユーザー数は 10k、応答時間は 200ms 未満を想定"
  }
}

返却内容:

{
  "session_id": "uuid",
  "stage": "po",
  "state": "refining",
  "requires_user_confirmation": true,
  "interaction_type": "awaiting_regeneration",
  "user_message": "📝 **あなたの回答を受け取りました**...",
  "role_prompt": "<ユーザーの回答を含む更新されたプロンプト>",
  "engines": ["claude"],
  "pending_user_actions": ["regenerate_with_answers"]
}

approve - 現在の段階を承認 (SM 段階のみ)

{
  "action": "approve",
  "session_id": "uuid",
  "approved": true
}

返却内容 (開発段階に入るとき):

{
  "session_id": "uuid",
  "stage": "dev",
  "state": "generating",
  "requires_user_confirmation": true,
  "interaction_type": "awaiting_generation",
  "user_message": "✅ **スプリントプランが承認されました**\n\n次の段階に進みます: 開発者 - 実装\n\nスプリントプランには 3 つのスプリントが含まれています:\n1. スプリント 1: インフラストラクチャ\n2. スプリント 2: 核心機能\n3. スプリント 3: 最適化と改善\n\n⚠️ 重要: 開発範囲を明示的に指定してください...",
  "role_prompt": "<開発者プロンプト>",
  "engines": ["codex"],
  "pending_user_actions": ["specify_sprint_scope_then_generate"]
}

重要 - 開発段階の動作:

• スプリントプランを承認した後、ワークフローは開発段階に入りますが、自動的に開発は開始されません。
• ユーザーは明示的に開発範囲を指定する必要があります。
  • "開発を開始する" / "start development" → すべてのスプリントを実装 (デフォルト)
  • "スプリント 1 を開発する" / "implement sprint 1" → スプリント 1 のみを実装
• これにより、ユーザーは何をいつ実装するかを完全にコントロールできます。

status - ワークフローの状態を照会

{
  "action": "status",
  "session_id": "uuid"
}

返却内容:

{
  "session_id": "uuid",
  "current_stage": "dev",
  "current_state": "generating",
  "stages": {...},
  "artifacts": [...]
}

📁 ファイル構造

あなたのプロジェクト

your-project/
├── .bmad-task/
│   ├── session-abc-123.json          # ワークフローの状態 (コンテンツ参照付き)
│   ├── task-mapping.json             # session_id → タスク名のマッピング
│   └── temp/
│       └── abc-123/                  # 一時的なコンテンツファイル
│           ├── po_claude_result_xxx.md
│           ├── po_codex_result_xxx.md
│           └── po_final_result_xxx.md
├── .claude/
│   └── specs/
│       └── implement-user-login/     # タスク名 (人間が読みやすいスラッグ)
│           ├── 01-product-requirements.md
│           ├── 02-system-architecture.md
│           ├── 03-sprint-plan.md
│           ├── 04-dev-reviewed.md
│           └── 05-qa-report.md
└── src/

セッション状態ファイル

{
  "session_id": "abc-123",
  "task_name": "implement-user-login",
  "cwd": "/path/to/project",
  "objective": "ユーザーログインを実装する",
  "current_stage": "dev",
  "current_state": "generating",
  "stages": {
    "po": {
      "status": "completed",
      "claude_result_ref": {
        "summary": "最初の 300 文字...",
        "file_path": ".bmad-task/temp/abc-123/po_claude_result_xxx.md",
        "size": 12450,
        "last_updated": "2025-01-15T10:30:00Z"
      },
      "final_result_ref": {...},
      "score": 92,
      "approved": true
    },
    ...
  },
  "artifacts": [".claude/specs/implement-user-login/01-product-requirements.md", ...]
}

🎨 エンジン設定

PO とアーキテクト段階 (動的エンジン選択)

• デフォルト: Claude のみ (シングルエンジン)
• デュアルエンジン: 目的に "codex" または "使用 codex" が含まれる場合に有効化
• デュアルエンジンが有効な場合:
  • Claude と Codex の両方を呼び出す
  • それぞれが独立したソリューションを生成する
  • BMAD-MCP が結果をマージする:
    • 両方が ≥ 90 の場合: スコアが高い方を選択
    • 片方が ≥ 90 の場合: その方を選択
    • 両方が < 90 の場合: スコアが高い方を選択し、改良する
• 対話型の明確化:
  • 最初の反復: ギャップを特定し、3 - 5 個の明確化の質問を生成
  • ユーザーが質問に回答
  • 回答に基づいて再生成
  • スコアが ≥ 90 になるまで反復

SM 段階 (Claude のみ)

• Claude のみを呼び出す
• スクラム計画には Codex は必要ない

開発/レビュー/QA 段階 (Codex のみ)

• Codex MCP のみを呼び出す
• コードタスクには GPT - 5 を使用
• 重要: model: "gpt-5" を使用する (NOT "gpt-5-codex")
• パラメータ:
  • model: "gpt-5"
  • sandbox: "danger-full-access"
  • approval-policy: "on-failure"

🔄 ワークフローの流れ

graph TD
    A[開始] --> B[PO 段階: 生成]
    B --> C{質問があるか?}
    C -->|はい| D[明確化: ユーザーの回答]
    D --> E[改良: 再生成]
    E --> F{スコア >= 90 か?}
    C -->|いいえ| F
    F -->|いいえ| C
    F -->|はい| G[確認待ち]
    G -->|確認| H[保存 + アーキテクト段階]
    H --> I{質問があるか?}
    I -->|はい| J[明確化: ユーザーの回答]
    J --> K[改良: 再生成]
    K --> L{スコア >= 90 か?}
    I -->|いいえ| L
    L -->|いいえ| I
    L -->|はい| M[確認待ち]
    M -->|確認| N[保存 + SM 段階]
    N -->|承認| O[開発段階]
    O --> P[レビュー段階]
    P --> Q[QA 段階]
    Q --> R[完了]

🛠️ 開発

プロジェクト構造

bmad-mcp/
├── src/
│   ├── index.ts              # メインの MCP サーバー
│   └── master-prompt.ts      # すべての役割プロンプト
├── dist/                     # コンパイルされた出力
├── package.json
├── tsconfig.json
└── README.md

ビルド

npm run build

開発モード

npm run dev  # ウォッチモード

ローカルでテスト

npm run build
node dist/index.js

📚 マスターオーケストレーターの設計

すべての役割プロンプトは単一の master-prompt.ts ファイルに埋め込まれています。

• 集中管理: すべての役割が一箇所にまとまっています。
• ワークフロー定義: 明確な段階の順序。
• エンジン設定: 各段階で使用するエンジン。
• 品質ゲート: スコアの閾値と承認ポイント。

🤝 Codex MCP との統合

開発/レビュー/QA 段階で Codex を呼び出すときは以下のようにします。

// Claude Code が Codex MCP を呼び出す
await callTool("codex", {
  prompt: role_prompt,  // bmad-task からのもの
  model: "gpt-5",  // 重要: "gpt-5" を使用する、"gpt-5-codex" ではない
  sandbox: "danger-full-access",
  "approval-policy": "on-failure"
});

⚙️ 設定

品質閾値

master-prompt.ts で定義されています。

quality_gates: {
  po: { min_score: 90, approval_required: true },
  architect: { min_score: 90, approval_required: true },
  sm: { approval_required: true },
  dev: {},
  review: {},
  qa: {}
}

成果物のファイル名

artifacts: {
  po: "01-product-requirements.md",
  architect: "02-system-architecture.md",
  sm: "03-sprint-plan.md",
  dev: "code-implementation",
  review: "04-dev-reviewed.md",
  qa: "05-qa-report.md"
}

🔍 トラブルシューティング

サーバーが起動しない場合

# インストールを確認
which bmad-mcp

# 直接テスト
bmad-mcp

ツール名のエラー

• 重要: ツール名は bmad-task であり、bmad ではありません。
• コードでは callTool("bmad-task", {...}) を使用してください。
• Claude Code の設定では bmad-task をツール名として使用してください。

セッションが見つからない場合

• .bmad-task/ ディレクトリに書き込み権限があることを確認してください。
• session_id が正しいことを確認してください。
• cwd パスが絶対パスであることを確認してください。

スコアが検出されない場合

• 生成されたコンテンツに Quality Score: X/100 または JSON 内に "quality_score": 92 が含まれていることを確認してください。
• スコアの形式がパターン (0 - 100) に一致することを確認してください。
• PO/アーキテクト段階を進むにはスコアが ≥ 90 である必要があります。

明確化ワークフローの問題

• state: "clarifying" が表示された場合、ユーザーは answer アクションで質問に回答する必要があります。
• 自動的に回答を生成しないでください - 実際のユーザー入力を待ってください。
• 進む前に requires_user_confirmation: true を確認してください。

📝 ライセンス

MIT

🙋 サポート

• ドキュメント: この README
• 問題報告: GitHub の Issues
• 参考: https://github.com/cexll/myclaude

BMAD で開発を変革しましょう - 1 つのワークフローで完全なアジャイルプロセスを実現し、品質を保証します。