multi-agent-mcp
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@multi-agent-mcpinit tmux workspace for /project/foo with session bug-123"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Multi-Agent MCP
AI CLI(Claude Code / Codex / Gemini / Cursor)+ tmux + git worktree (または非gitディレクトリ)を使用したマルチエージェントワークフローの MCP サーバー。
概要
このMCPサーバーは、複数のAI CLIインスタンスを tmux セッションで管理し、並列作業を実現します。
MCP_ENABLE_GIT=false を設定すると、git 管理されていないディレクトリでも実行できます。
Gitモード
モード | 設定 | 挙動 |
Git有効(デフォルト) |
| git リポジトリ前提。worktree/gtr 機能を利用可能 |
Git無効 |
| 非gitディレクトリで実行可能。git/worktree/gtr 機能は無効 |
init_tmux_workspace(enable_git=...) を指定すると、.multi-agent-mcp/config.json に保存され、
以降の同一プロジェクト実行で参照されます。
階層構造
Owner (1体): 全体指揮、タスク分解、Issue作成
Admin (1体): Worker管理、進捗管理、ダッシュボード更新
Worker (標準6体 / 最大16体): 割り当てられたタスクの実行
対応 AI CLI 一覧
CLI | 識別子 | 備考 |
Claude Code |
| デフォルト構成で利用可能 |
Codex |
| デフォルト構成で利用可能 |
Gemini |
| デフォルト構成で利用可能 |
Cursor |
| 既定コマンドは |
Related MCP server: Claude Team MCP Server
必要条件
Python 3.10以上
tmux
uv(推奨)または pip
最短セットアップ
MCP クライアントに
multi-agent-mcpを登録します。 Claude / Codex は次の CLI 例を使い、Gemini / Cursor などで CLI サブコマンドが異なる場合は この後の JSON 設定例と同じcommand=uvx/args=[...]を登録してください。クライアントを再起動し、MCP サーバーへ再接続します。
クライアント上で
init_tmux_workspace("/path/to/project", session_id="issue-123")を実行して ワークスペースを初期化します。非 git ディレクトリではenable_git=falseを指定します。
インストール
GitHub から直接インストールできます(リポジトリの clone は不要)。
CLI で追加
通常運用では --reinstall なしを推奨します。
追加コマンドは次の「設定の追加・削除(再インストールとは別)」を参照してください。
設定の追加・削除(再インストールとは別)
Claude
# 追加(--reinstall なし)
claude mcp add --scope user multi-agent-mcp -- uvx --from git+https://github.com/shiiman/multi-agent-mcp multi-agent-mcp
# 削除
claude mcp remove multi-agent-mcpCodex
# 追加(--reinstall なし)
codex mcp add multi-agent-mcp -- uvx --from git+https://github.com/shiiman/multi-agent-mcp multi-agent-mcp
# 削除
codex mcp remove multi-agent-mcpGemini / Cursor など
CLI からの追加コマンドが未提供、または実装差分があるクライアントでは、 次の「設定ファイルに直接記述」の JSON 例と同じ内容を登録してください。
設定ファイルに直接記述
グローバル設定 (~/.claude.json):
{
"mcpServers": {
"multi-agent-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"--from", "git+https://github.com/shiiman/multi-agent-mcp",
"multi-agent-mcp"
]
}
}
}プロジェクト設定 (.mcp.json をプロジェクトルートに作成):
{
"mcpServers": {
"multi-agent-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"--from", "git+https://github.com/shiiman/multi-agent-mcp",
"multi-agent-mcp"
]
}
}
}自動更新について
--reinstall オプションを付けると、起動時に毎回 GitHub から最新版を再インストールします。
Note:
--refreshオプションでは Git リポジトリのキャッシュが効いたままになり、更新が反映されないことがあります。確実に最新版を使用するには--reinstallを推奨します。
--reinstall なし運用で更新したい場合は、次の「必要なときだけ再インストールする手順」を実行してください。
必要なときだけ再インストールする手順(Claude/Codex 共通):
# 1) 1回だけ再インストール(通常運用では毎回不要)
uv tool install --force --from git+https://github.com/shiiman/multi-agent-mcp multi-agent-mcp
# 2) 使用中のクライアントを再起動して MCP を再接続
# - Claude を使っている場合: Claude を再起動
# - Codex を使っている場合: Codex を再起動
# 3) 反映確認(使用クライアントに応じて実行)
claude mcp list
codex mcp get multi-agent-mcp
# 4) 反映されない場合のみキャッシュクリア
uv cache clean multi-agent-mcp上記の JSON 例は、mcpServers 形式を採用しているクライアントであれば
Claude / Codex 以外でも同様の考え方で利用できます。
設定の確認
# Claude
claude mcp list
# Codex
codex mcp list提供するTools(90個)
セッション管理(4個)
Tool | 説明 |
| ターミナルを開いてtmuxワークスペースを構築(Admin 1 + Worker 1-6 の7ペイン) |
| 全エージェントを終了しリソースを解放 |
| 全タスクの完了状態をチェック |
| 全タスク完了時にワークスペースをクリーンアップ |
エージェント管理(6個)
Tool | 説明 |
| 新しいエージェントを作成(tmuxセッション起動) |
| 全エージェントの一覧を取得 |
| 指定エージェントの詳細ステータスを取得 |
| エージェントを終了 |
| エージェントにロールテンプレートを渡してAI CLIを起動 |
| 複数のWorkerを並列で作成しタスクを割り当て |
コマンド実行(5個)
Tool | 説明 |
| エージェントにコマンドを送信 |
| エージェントのtmux出力を取得 |
| タスク指示をファイル経由でWorkerに送信 |
| エージェントのtmuxセッションをターミナルで開く |
| 全エージェント(または特定役割)にコマンド送信 |
Git Worktree管理(7個)
Tool | 説明 |
| 新しいgit worktreeを作成(git有効時のみ) |
| worktree一覧を取得(git有効時のみ) |
| worktreeを削除(git有効時のみ) |
| エージェントにworktreeを割り当て(git有効時のみ) |
| worktreeのgitステータスを取得(git有効時のみ) |
| gtr (git-worktree-runner) の利用可否を確認(git有効時のみ) |
| gtr aiでworktreeをAIツールで開く(git有効時のみ) |
create_worktree の引数契約
create_worktree は以下の引数契約です(branch_name 引数は存在しません)。
create_worktree(
repo_path="/path/to/repo",
worktree_path="/path/to/worktree",
branch="feature/xxx",
create_branch=True,
base_branch="main",
caller_agent_id="admin-or-owner-id",
)マージ(1個)
Tool | 説明 |
| 完了タスクの作業ブランチを commit なしで統合ブランチへ展開 |
IPC/メッセージング(5個)
Tool | 説明 |
| エージェント間でメッセージを送信 |
| エージェントのメッセージを読み取る |
| 未読メッセージ数を取得 |
| Owner の待機ロックを手動解除 |
| エージェントをIPCシステムに登録 |
ダッシュボード/タスク管理(15個)
Tool | 説明 |
| 新しいタスクを作成 |
| 終端タスクを再開(再実行用) |
| タスクのステータスを更新(Admin専用) |
| タスクをエージェントに割り当て(Admin専用) |
| タスク一覧を取得 |
| Workerがタスクの進捗を報告 |
| WorkerがAdminにタスク完了を報告(Worker専用) |
| タスクの詳細を取得 |
| タスクを削除 |
| ダッシュボード全体を取得 |
| ダッシュボードのサマリーを取得 |
| 現在のコスト推定を取得 |
| コスト警告の閾値を設定 |
| コストカウンターをリセット |
| コストサマリーを取得 |
create_task の metadata 運用
create_task では、タスク説明文字列だけでなく metadata を渡す運用を推奨します。
task_kind: タスク種別(例:implementation/qa/docs/report)requires_playwright: Playwright 検証が必要なタスクか(true/false)output_dir: 成果物の出力先(例:.multi-agent-mcp/{session_id}/reports)
update_task_status の遷移制約
update_task_statusは通常の前進遷移に使用します。completed/failed/cancelledの終端状態になったタスクを再開するときは、update_task_statusで直接戻さずreopen_taskを使用してください。
調査レポートの出力ルール
調査・検証系タスクの Markdown 成果物は
.multi-agent-mcp/{session_id}/reports/*.mdに出力します。出力先は
create_task.metadata.output_dirで明示し、Worker 指示にも同じパスを記載します。
Gtrconfig(3個)
Tool | 説明 |
| .gtrconfigの存在確認と内容取得 |
| プロジェクト構造を解析して推奨設定を提案 |
| .gtrconfigを自動生成 |
テンプレート(6個)
Tool | 説明 |
| 利用可能なテンプレート一覧を取得 |
| 特定テンプレートの詳細を取得 |
| 特定ロールのワークフローガイドを取得 |
| 利用可能なロールガイド一覧を取得 |
| 利用可能なレポートテンプレート一覧を取得 |
| 特定レポートテンプレートの内容を取得 |
スケジューラー(3個)
Tool | 説明 |
| タスクをスケジューラーキューに追加 |
| 空いているWorkerにタスクを自動割り当て |
| 現在のタスクキューを取得 |
ヘルスチェック(6個)
Tool | 説明 |
| 特定エージェントのヘルスチェックを実行 |
| 全エージェントのヘルスチェックを実行 |
| 異常なエージェント一覧を取得 |
| エージェントの復旧を試みる |
| Worker を完全復旧(agent/worktree再作成+タスク再割り当て) |
| Worker監視と段階復旧(attempt→full→failed化)を実行 |
ペルソナ(3個)
Tool | 説明 |
| タスクの説明からタスクタイプを検出 |
| タスクに最適なペルソナを取得 |
| 利用可能なペルソナ一覧を取得 |
メモリ管理(19個)
Tool | 説明 |
| 知識をプロジェクトメモリに保存 |
| プロジェクトメモリから知識を検索 |
| キーでメモリエントリを取得 |
| メモリエントリ一覧を取得 |
| メモリエントリを削除 |
| メモリのサマリー情報を取得 |
| アーカイブされたメモリを検索 |
| アーカイブエントリ一覧を取得 |
| アーカイブからエントリを復元 |
| アーカイブのサマリー情報を取得 |
| グローバルメモリに保存(全プロジェクト共通) |
| グローバルメモリから検索 |
| グローバルメモリエントリ一覧を取得 |
| グローバルメモリのサマリーを取得 |
| グローバルメモリエントリを削除 |
| グローバルアーカイブを検索 |
| グローバルアーカイブ一覧を取得 |
| グローバルアーカイブからエントリを復元 |
| グローバルアーカイブのサマリーを取得 |
スクリーンショット(4個)
Tool | 説明 |
| スクリーンショットディレクトリを取得 |
| スクリーンショット一覧(最新N件) |
| 指定ファイルを読み取り(Base64) |
| 最新のスクリーンショットを読み取り |
モデルプロファイル(3個)
Tool | 説明 |
| 現在のプロファイルを取得 |
| プロファイルを切り替え(standard/performance) |
| プロファイルの設定詳細を取得 |
switch_model_profile の方針
モデルプロファイルの正準保存先は
.multi-agent-mcp/.env(MCP_MODEL_PROFILE_ACTIVE)です。switch_model_profileは.envのみを更新し、config.jsonへは保存しません。config.jsonはセッション設定(session_id,enable_gitなど)専用です。
主要フィールド(公開I/F)
Agent
主要フィールド:
id,role,status,tmux_session,working_dir,worktree_path,current_taskグリッド/CLI 関連:
session_name,window_index,pane_index,ai_cli,ai_bootstrapped
Dashboard / Task
TaskInfo:task_file_path,metadata,started_at,completed_at,error_messagemetadataにはrequested_descriptionや運用キー(task_kindなど)を保持しますDashboard 運用フィールド:
session_started_at,session_finished_at,process_crash_count,process_recovery_count
使用例
# ターミナルを開いてtmuxワークスペースを構築(git有効)
init_tmux_workspace("/path/to/project", session_id="issue-123")
# 非gitディレクトリで実行
init_tmux_workspace("/path/to/non-git-dir", session_id="issue-123", enable_git=false)
# Ownerエージェントを作成
create_agent(
role="owner",
working_dir="/path/to/project",
)
# Workerエージェントを作成
create_agent(
role="worker",
working_dir="/path/to/worktree1",
caller_agent_id="admin-or-owner-id",
)
create_agent(
role="worker",
working_dir="/path/to/worktree2",
caller_agent_id="admin-or-owner-id",
)
# エージェント一覧を確認
list_agents(caller_agent_id="admin-or-owner-id")
# Workerにコマンドを送信
send_command(
agent_id="abc12345",
command="echo 'Hello from Worker'",
caller_agent_id="admin-or-owner-id",
)
# 出力を取得
get_output(
agent_id="abc12345",
lines=100,
caller_agent_id="admin-or-owner-id",
)
# 全Workerにコマンドをブロードキャスト
broadcast_command(
command="git status",
role="worker",
caller_agent_id="admin-or-owner-id",
)
# クリーンアップ
cleanup_workspace(caller_agent_id="owner-id")ドキュメント
各システムの詳細な解説は以下を参照してください:
ドキュメント | 説明 |
永続ファイル/ディレクトリ構造と命名規則 | |
エージェント間メッセージ通信の仕組み | |
知識の永続化・共有・アーカイブ機能 | |
Git worktree による分離作業環境 | |
タスク状態管理とダッシュボード表示 | |
Worker 監視、段階復旧、daemon 運用 | |
完了タスクブランチの統合運用 |
環境変数
変数 | デフォルト | 説明 |
| .multi-agent-mcp | MCP設定ディレクトリ名 |
| true | git 前提機能を有効化するか(falseで非gitディレクトリ許可) |
| false | worktreeを使用するか( |
| false | 画像タスクの Cursor ルーティングを有効化するか(既定 false) |
| main | メインウィンドウ名(Admin + Worker 1-6) |
| workers- | 追加Workerウィンドウ名のプレフィックス |
| 2 | 追加ウィンドウの行数 |
| 5 | 追加ウィンドウの列数 |
| 10 | 追加ウィンドウのWorker数 |
| 10.0 | コスト警告の閾値(USD) |
| 5000 | 1回のAPI呼び出しあたりの推定トークン数 |
|
| モデル別1000トークン単価テーブル(JSON) |
| 0.01 | 未定義モデル向けの汎用単価(USD/1K) |
| 60 | ヘルスチェック監視ループの実行間隔(秒) |
| 600 | 無応答判定の閾値(秒) |
| 120 |
|
| 3 | 同一worker/taskに対する復旧試行回数の上限 |
| 3 | 実作業なし検知が連続したとき daemon を自動停止する閾値 |
| 3 | Codex への Enter 再送回数の上限 |
| 250 | Codex への Enter 再送間隔(ミリ秒) |
| 2.0 | tmux への連続送信時に挟む最小待機秒数 |
| auto | ターミナルアプリ(auto: cmux→ghostty→iterm2→terminal) |
| standard | モデルプロファイル(standard/performance) |
| codex | standardプロファイルのAI CLI |
| gpt-5.5 | standardプロファイルのAdminモデル |
| gpt-5.5 | standardプロファイルのWorkerモデル |
| 6 | standardプロファイルのWorker上限 |
| 4000 | standardプロファイルのAdmin思考トークン数 |
| 4000 | standardプロファイルのWorker思考トークン数 |
| medium | standardプロファイルのAdmin推論強度 |
| medium | standardプロファイルのWorker推論強度 |
| codex | performanceプロファイルのAI CLI |
| gpt-5.5 | performanceプロファイルのAdminモデル |
| gpt-5.5 | performanceプロファイルのWorkerモデル |
| 16 | performanceプロファイルのWorker上限 |
| 30000 | performanceプロファイルのAdmin思考トークン数 |
| 4000 | performanceプロファイルのWorker思考トークン数 |
| high | performanceプロファイルのAdmin推論強度 |
| high | performanceプロファイルのWorker推論強度 |
| - | プロジェクトルート(.env読み込み用) |
| opus | Claude CLIのAdminデフォルトモデル |
| sonnet | Claude CLIのWorkerデフォルトモデル |
| gpt-5.5 | Codex CLIのAdminデフォルトモデル |
| gpt-5.5 | Codex CLIのWorkerデフォルトモデル |
| gemini-3-pro-preview | Gemini CLIのAdminデフォルトモデル |
| gemini-3-flash-preview | Gemini CLIのWorkerデフォルトモデル |
| composer-1.5 | Cursor CLIのAdminデフォルトモデル |
| composer-1.5 | Cursor CLIのWorkerデフォルトモデル |
| uniform | Worker CLI設定モード(uniform/per-worker) |
| (empty) | per-workerモードでのWorker別CLI設定(未設定時はアクティブプロファイルCLIを利用) |
| (empty) | per-workerモードでのWorker別モデル設定(未設定時はプロファイルのWORKER_MODEL) |
| 3 | 品質チェックの最大イテレーション回数 |
| 3 | 同一問題の繰り返し上限 |
| true | 品質ゲートを厳格に適用するか |
| 1000 | メモリの最大エントリ数 |
| 90 | メモリエントリの保持期間(日) |
| [".png",".jpg",...] | スクリーンショットとして認識する拡張子 |
Worker上限は MCP_MODEL_PROFILE_ACTIVE に応じて
MCP_MODEL_PROFILE_STANDARD_MAX_WORKERS / MCP_MODEL_PROFILE_PERFORMANCE_MAX_WORKERS
のどちらかが適用されます。
MCP_MODEL_COST_TABLE_JSON のデフォルトでは gemini-3-pro-preview / gemini-3-flash-preview
を使用し、後方互換のため gemini-3-pro / gemini-3-flash キーも併記しています。
ディレクトリ構造
init_tmux_workspace 実行時に以下のディレクトリと .env ファイルが自動作成されます:
{project_root}/.multi-agent-mcp/
├── .env # プロジェクト設定(テンプレート付き)
├── config.json # 実行時設定(session_id / enable_git など)
├── memory/ # プロジェクトメモリ
├── screenshot/ # スクリーンショット保存先
└── {YYYYMMDD}-{HHMMSS}-{session_id}/ # セッション別(時系列プレフィックス)
├── dashboard/ # ダッシュボード
├── tasks/ # タスクファイル
└── reports/ # 調査/検証レポート(*.md)プロジェクト別設定
プロジェクトごとに設定を変更する場合、.multi-agent-mcp/.env ファイルを編集してください。
init_tmux_workspace 実行時に、設定可能な全変数がコメント付きで自動生成されます。
設定の優先順位:
環境変数(最優先)
.multi-agent-mcp/.envファイルデフォルト値
enable_git のみ、実行時は以下の優先順位で解決されます:
init_tmux_workspace(enable_git=...)の引数.multi-agent-mcp/config.jsonのenable_git環境変数 /
.envデフォルト値(
true)
gitignore 推奨
タスクファイルやダッシュボードは .multi-agent-mcp/ ディレクトリに出力されます。
このディレクトリは一時ファイルなので、.gitignore に追加することを推奨します。
# プロジェクトの .gitignore に追加
echo ".multi-agent-mcp/" >> .gitignore開発(コントリビューター向け)
ローカルで開発する場合は、リポジトリをクローンしてください。
# リポジトリをクローン
git clone https://github.com/shiiman/multi-agent-mcp.git
cd multi-agent-mcp
# 開発用依存関係をインストール
uv sync --all-extras
# テストを実行
uv run pytest
# 高速反復(キーワードで対象テストのみ)
uv run pytest -k healthcheck
# 高速反復(ファイル単位)
uv run pytest tests/test_healthcheck_manager.py
# リンターを実行
uv run ruff check src/トラブルシューティング
tmux セッションが見つからない
エラー: tmux セッションが見つかりません原因: tmux がインストールされていないか、ワークスペースが初期化されていません。
対処法:
tmux -Vで tmux のインストールを確認init_tmux_workspaceでワークスペースを初期化
Worker が応答しない(stall 検出)
原因: AI CLI プロセスがハングアップしている可能性があります。
対処法:
healthcheck_agentで状態を確認attempt_recoveryで軽量復旧を試行それでも改善しない場合は
full_recoveryで完全復旧
dashboard.md が読み込めない
原因: YAML Front Matter のフォーマットが壊れている可能性があります。
対処法:
.multi-agent-mcp/{session_id}/dashboard/dashboard.mdを削除get_dashboardを実行すると自動で再生成されます
MCP サーバーが起動しない
原因: 依存パッケージのバージョン不整合の可能性があります。
対処法:
# キャッシュクリア + 再インストール
uv cache clean multi-agent-mcp
uv tool install --force --from git+https://github.com/shiiman/multi-agent-mcp multi-agent-mcpライセンス
MIT
This server cannot be installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Latest Blog Posts
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/shiiman/multi-agent-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server