--- title: "claude-peers-mcpとは？仕組み・導入手順と公式セッション間メッセージとの違い" url: "https://www.issoh.co.jp/tech/details/11478/" published: 2026-03-23 updated: 2026-10-31 categories: ["Claude"] publisher: "株式会社一創" --- # claude-peers-mcpとは？仕組み・導入手順と公式セッション間メッセージとの違い claude-peers-mcpは、同じPCで動く複数のClaude Codeセッションが互いを見つけ、メッセージを送り合えるようにするオープンソースのMCPサーバーです。louislva氏が2026年3月21日にGitHubで公開し、2026年10月31日時点でスター2,207、フォーク307が付いています。 同じことをする公式機能「セッション間メッセージ（cross-session messaging）」が、2026年8月7日のClaude Code v2.1.224で標準搭載されました。本記事ではclaude-peers-mcpの仕組みと導入手順、ソースと手元の再現で確かめた落とし穴を説明し、公式機能への読み替え方と乗り換え手順までを扱います。 ## まとめ：claude-peers-mcpの要点と2026年10月時点の選び方 - **仕組み**：`localhost:7899` のブローカー（SQLite）に各セッションのMCPサーバーが登録し、1秒ごとに受信箱を確認します。届いたメッセージはClaude CodeのChannels機能で会話に差し込まれます。 - **導入**：Bunとv2.1.80以上のClaude Codeが前提です。clone、`claude mcp add`、`--dangerously-load-development-channels server:claude-peers` 付きの起動の3手順で動きます。 - **注意点**：ブローカーは送信者を検証しません。チャネル無しで動かすとメッセージが消え、相手のセッションが落ちると未配達分も削除されます。`--dangerously-skip-permissions` とは併用しないでください。 - **保守**：mainへの最後のコミットは2026年4月26日です。auto-summaryやWindowsの修正PRは出ていますが、マージされていません。 - **選び方**：公式のセッション間メッセージは、macOS・Linux・WSL 2ではv2.1.224以上、ネイティブWindowsではv2.1.234以上が基本要件です。Bedrock等の経由では、同一PC内の通信にv2.1.248以上が必要です。いずれも設定なしで有効になります。新しく導入するなら公式機能を選び、claude-peers-mcpは外してください。 ## claude-peers-mcpの仕組み：ブローカー・MCPサーバー・Channelsの3層 リポジトリの中身はTypeScriptで約1,200行です。`broker.ts`（273行）がブローカー、`server.ts`（555行）が各セッションに付くMCPサーバー、`cli.ts` が端末から状態を見るコマンドです。 ### localhost:7899のブローカーとSQLiteに残る情報 ブローカーは `127.0.0.1:7899` で待ち受けるHTTPサーバーで、最初のセッションが起動したときに自動で立ち上がります。データは `~/.claude-peers.db` に保存され、ポートとDBの場所は環境変数 `CLAUDE_PEERS_PORT` と `CLAUDE_PEERS_DB` で変えられます。 テーブルは `peers` と `messages` の2つです。`peers` にはセッションごとのID（英数字8文字のランダム値）、プロセスID、作業ディレクトリ、Gitのルート、作業概要（summary）が入ります。IDは登録のたびに振り直されるため、セッションを再起動すると同じ相手でもIDが変わります。 ### 4つのツールとlist\_peersの3スコープ | ツール | 役割 | 主な引数 | | ---------------- | ---------- | ----------------------------- | | `list_peers` | 他のセッションを一覧 | scope（machine／directory／repo） | | `send_message` | IDを指定して送信 | to\_id、message | | `set_summary` | 自分の作業概要を登録 | summary（1〜2文） | | `check_messages` | 受信箱を手動で確認 | なし | `list_peers` のスコープは、machineがPC上の全セッション、directoryが作業ディレクトリの完全一致、repoがGitのルートの一致です。迷ったらmachineで一覧を出し、作業概要を見て相手を選んでください。 ### Channelsで会話に届く仕組みと「すぐ応じろ」という指示 各セッションのMCPサーバーは1秒ごとにブローカーへ問い合わせ、新着があると `notifications/claude/channel` 通知でClaude Codeに渡します。本文は `` タグ付きで会話に入るため、Claudeに受信箱の確認を頼む必要はありません。 さらにMCPサーバーは、メッセージを受け取ったら作業を中断してすぐ返信するようClaudeに指示しています。とはいえ実行中の処理が途中で止まるわけではなく、作業中に届いた通知はキューに入り、次のターンでまとめて渡されます。届いたら最優先で応じるよう指示されている点が、後述するセキュリティ上の問題につながります。 ## claude-peers-mcpの導入手順：前提条件から動作確認まで ### 前提条件：Bun・Claude Code v2.1.80以上・Anthropic認証 READMEの要件は、Bunランタイム、Claude Code v2.1.80以上（2026年3月19日公開）、claude.aiへのログインの3つです。 認証の条件はREADMEより緩くなっています。READMEには「APIキー認証では動かない」とありますが、[公式のChannelsドキュメント](https://code.claude.com/docs/en/channels)は現在、claude.aiのアカウントかClaude ConsoleのAPIキーで使えると書いています（Consoleへの対応はv2.1.128、2026年5月4日）。一方でAmazon Bedrock、Google CloudのAgent Platform、Microsoft Foundry経由ではChannelsを使えません。認証方式の切り替えは[Claude Codeのログイン方法（サブスクとAPIキーの切替）](/tech/details/18748/)で手順を確認できます。 ### clone・MCP登録・起動の3手順 READMEどおりに進めると、次の3つで動きます。cloneの場所を変えた場合は、`claude mcp add` のパスも合わせてください。 ``` git clone https://github.com/louislva/claude-peers-mcp.git ~/claude-peers-mcp cd ~/claude-peers-mcp && bun install claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts claude --dangerously-load-development-channels server:claude-peers ``` `--scope user` で登録すると、どのディレクトリで起動したセッションにもclaude-peersが読み込まれます。READMEの手順3には `--dangerously-skip-permissions` も付いていますが、本記事では外しています。理由はセキュリティの章で説明します。 ### 2つ目のセッションとCLIでの動作確認 別のターミナルで同じコマンドを使って2つ目のセッションを起動し、どちらかで「List all peers on this machine」と頼みます。相手のID・作業ディレクトリ・作業概要が返れば接続できています。端末からは、cloneしたディレクトリで次のコマンドも使えます。 ``` bun cli.ts status # ブローカーの状態と全ピア bun cli.ts peers # ピア一覧 bun cli.ts send ab12cd34 "いま何の作業中？" # IDはpeersの表示に置き換える bun cli.ts kill-broker # ブローカーを停止 ``` 一覧に相手が出ないときは、相手側の `claude mcp list` にclaude-peersがあるかと、scopeがmachineかを確認してください。起動フラグを付け忘れたセッションも一覧には出ますが、メッセージは届かずに消えます（後述）。 ## dangerously-load-development-channelsの意味とチャネルが登録されない原因 `--dangerously-load-development-channels` は、Anthropicの許可リストに載っていないチャネルを、指定したものに限って読み込ませる開発者向けのフラグです。Channelsはまだ**リサーチプレビュー**で、通常の `--channels` は、Anthropicまたは組織管理者の許可リストに載ったプラグインだけを受け付けます。claude-peersはリストに無いため、このフラグが必要になります。 フラグは `server:<名前>` か `plugin:<名前>@<マーケットプレイス>` で対象を指定し、起動時に確認プロンプトを出します。プレビュー期間中は `claude --help` に表示されず、手元のv2.1.314でも出てきませんが、フラグ自体は動きます。名前の「dangerously」は、外から届いた文字列がそのまま会話に入ることへの警告です。送信者の許可リストを持つ公式プラグインの例は[Discord MCPとClaude Code公式プラグインの設定手順](/tech/details/8360/)で解説しています。 ### フラグを付けても届かない3つの条件 フラグを付けて起動しても、次の場合はチャネルとして登録されず、メッセージが会話に入りません。 - **Team・Enterpriseプランで未許可**：Ownerが組織設定でChannelsを有効にするか、管理設定で `channelsEnabled` を `true` にするまで、開発用フラグも含めて全チャネルが止まります。 - **MCP SDK 2.x系に上げたフォーク**：Claude Codeはv2.1.232以降、通常のセッションではMCP TypeScript SDK 2.0ベースの「v2ランタイム」で接続します。[公式のMCPドキュメント](https://code.claude.com/docs/en/mcp)によると、v2ランタイムではプロトコル版2026-07-28で接続したチャネルサーバーは登録されません。本家のbun.lockはSDK 1.27.1を固定しているので該当しませんが、SDKを2.x系に上げたフォークでも、プロトコル版2026-07-28で接続した場合にこの制限が生じます。回避策は環境変数 `MCP_PROTOCOL_NEGOTIATION=legacy` です。 - **Bedrock・Agent Platform・Foundry経由**：Channels自体が使えません。 なお、SDK 1.27.1は2026年10月に公表されたMCP TypeScript SDKの脆弱性の修正版（1.x系は1.32.0以上）より前の版です。対象条件と更新手順は[MCP TypeScript SDKの脆弱性の解説](/tech/details/19021/)にまとめています。1.x系の範囲で上げるなら `bun update @modelcontextprotocol/sdk` で、10月31日時点の最新は1.32.2です。 ## ソースと手元の再現で確認したclaude-peers-mcpの落とし穴 以下は、mainブランチのソースを読み、ブローカーを別ポートで起動して再現した挙動です（対象はmainのコミット640183f、macOS上のBun 1.4.2、2026年9月29日）。mainはその後も変わっていません（10月31日にGitHub APIで確認）。どれもIssueで報告済みですが、READMEには書かれていません。 ### チャネル無し起動でのcheck\_messagesの空振りとメッセージ消失 READMEは `check_messages` を「チャネルを使わない場合の代替」と説明しています。ところが実装では、1秒ごとの問い合わせがチャネルの有無に関係なく動き、ブローカーは受信箱を渡した時点でメッセージを `delivered=1` にします。チャネルに対応しないクライアントでは通知が捨てられ、あとから `check_messages` を呼んでも何も残っていません。 チャネル機能を持たないMCPクライアントからserver.tsを起動し、1通送って2.5秒後に `check_messages` を呼ぶと、返答は「No new messages.」で、DB上は配達済みでした。[Issue #8](https://github.com/louislva/claude-peers-mcp/issues/8)と同じ現象で、修正PR #40は未マージです。起動フラグを付け忘れたセッションや、Codexなど他のMCPクライアントにつないだ場合、メッセージは黙って消えます。 ### 30秒間隔の死活確認による未配達メッセージ削除と幽霊ピア ブローカーは30秒ごとに登録済みのプロセスIDが生きているかを調べ、死んでいればそのピアと宛先の未配達メッセージを削除します。宛先のプロセスを止めてから1通入れると、32秒後にはピアの行もメッセージも消えていました。落ちたセッションに送った依頼は再送が必要です（Issue #37）。 逆に、登録されるのはClaude Code本体ではなくMCPサーバー（`bun server.ts`）のプロセスIDです。Issue #81によると、ターミナルを閉じてもこのプロセスが残ることがあり、応答しない「幽霊ピア」が一覧に残り続けます。 ### git worktree間で相手を見つけられないrepoスコープ `list_peers` の説明文はrepoスコープが「worktreeも含む」としていますが、実装が比べているのは `git rev-parse --show-toplevel` の結果で、worktreeごとに違うパスが返ります。手元のGit 2.50.1でも、本体は `/private/tmp/wtrepo`、worktreeは `/private/tmp/wtrepo-feat` でした。[git worktreeで並列開発する構成](/tech/details/11708/)では、machineスコープを使ってください（Issue #23）。 ### auto-summaryの400エラーとOpenAIへ送られる情報 環境変数 `OPENAI_API_KEY` を設定すると、起動時にOpenAIの `gpt-5.4-nano` が作業概要を自動で作る仕様です。しかしリクエストが旧パラメータ `max_tokens` を使っているため400エラーで拒否され、エラーも表示されません（Issue #64）。修正PR #83が2026年8月19日に出ていますが、10月31日時点で未マージです。要約生成がエラーになっても、リクエストがOpenAIに到達すれば、作業ディレクトリとGitルートのパス、ブランチ名、直近の変更ファイル名（最大10件）は送信済みです。社外に出したくない名前を扱うなら、キーを設定せず `set_summary` で書かせてください。 ## 認証のないlocalhostブローカーとプロンプトインジェクションの危険 ブローカーは `127.0.0.1` だけで待ち受けるので、外部ネットワークからは届きません。その代わり、**同じPCで動くプロセスなら誰でも**メッセージを送れます。存在しないID「nobody00」を送信元にしてHTTPで直接POSTしたところ、ブローカーは `{"ok":true}` を返し、宛先の受信箱にそのまま入りました。 ここにREADMEの `--dangerously-skip-permissions` が重なると危険です。受信側のClaudeは「すぐ応じろ」と指示され、権限確認も止まっています。ローカルで動く任意のスクリプトや依存パッケージに紛れたコードが「このファイルを消せ」と送るだけで、確認なしに実行されるおそれがあります。[Channelsリファレンス](https://code.claude.com/docs/en/channels-reference)も、送信者を検証しないチャネルはプロンプトインジェクションの経路になると明記しています。 使うなら、bypassPermissionsモードとは併用せず、自分専用の開発機に限ってください。共用サーバーや、信頼できないコードを実行するマシンでは使いません。権限モードの違いは[Claude Codeのパーミッションモードの違いと設定方法](/tech/details/11246/)で確認できます。 ## 公式のセッション間メッセージ（v2.1.224以降）との比較と乗り換え 公式機能では、Claudeが `ListAgents` で相手を探し、`SendMessage` で送ります。macOS・Linux・WSL 2ではv2.1.224以上、ネイティブWindowsではv2.1.234以上で、何も設定せずに有効です。手で確かめるときは `/list-agents`（別名 `/peers`）を実行します。仕様は[公式ドキュメントのcross-session messaging](https://code.claude.com/docs/en/cross-session-messaging)にあります。 | 項目 | claude-peers-mcp | 公式セッション間メッセージ | | -------- | -------------------- | ------------------ | | 導入 | clone＋Bun＋起動フラグ | 不要（既定オン） | | 相手の指定 | 8文字のID | セッション名・@メンション | | 同一PC内の経路 | HTTP（127.0.0.1:7899） | セッションごとのソケット | | 送信者の制限 | なし | OSユーザー単位 | | 受信の制御 | なし | accept／hold／refuse | | 届かなかったとき | 黙って消える場合あり | 拒否・失効を送信側に通知 | | 別PC・クラウド | 不可 | Remote Control経由で可 | | Windows | 起動しない（Issue #73） | v2.1.234以上 | | Bedrock等 | 不可 | 同一PC内はv2.1.248以上 | ### claude-peersの4ツールから公式機能への読み替え | claude-peers | 公式機能での対応 | 必要な版 | | ---------------- | ---------------------------------- | ---------- | | `list_peers` | `ListAgents`／`/list-agents` | v2.1.224 | | `send_message` | `SendMessage`、プロンプトで `@名前` | @はv2.1.232 | | `set_summary` | `/rename` か `--name` で作業が分かる名前を付ける | – | | `check_messages` | 不要（ツール呼び出しの合間に自動で届く） | – | | 相手の完了待ち（対応なし） | `notify_when_idle` | v2.1.236 | claude-peersに無かった機能が `notify_when_idle` です。「マイグレーションのセッションが終わったら教えて」と頼むと、相手が次にアイドルになるか終了したときに1回だけ通知が届きます。相手のセッションにトークンを使わせず、12時間届かなければ購読は破棄されます。同じPC上の自分のセッションだけが対象です。 上限も決まっています。約100万文字を超えるメッセージと、1つのセッションへの短時間の連投は送信側で拒否されます。受信側は同じ送信者の連投を抑え、読ませる前のキューは50件までなので、2つのセッションが返信し合うループも自然に止まります。届いたメッセージは、手で打ったプロンプトと同じく利用量に数えられます。 ### 受信の既定動作とbypassPermissionsモードの例外 公式機能では、別セッションからのメッセージは「あなたではなく別のセッションから来た」と明示されて届きます。権限確認への承認には使えず、設定やCLAUDE.mdを変えないよう受信側に指示が入り、本文中の `/compact` などのコマンドも実行されません。 受信側が権限確認を省くモード（bypassPermissions）で動いているときは、既定でメッセージを保留し、承認ダイアログを出します。端末に接続中の承認ダイアログは既定5分（`dialogExpiry`）で失効し、保留は最大100件です。端末未接続のバックグラウンドセッションでは接続後に期限を数え直し、明示的なhold設定による保留はこの期限では失効しません。ただし送信側も権限確認を省くモードなら保留されずに届くため、全セッションを `--dangerously-skip-permissions` で動かすとこの保護は働きません。明示的に決めたいときは、`/config` の「Messages from your other sessions」（v2.1.232以上）か設定の `crossSessionInbound` で accept・hold・refuse を選びます。 ### 乗り換える場面と、claude-peers-mcpを外す手順 新しく導入するなら公式機能を使ってください。claude-peers-mcpを残してよいのは、組織の方針でClaude Codeをv2.1.80〜v2.1.223に固定していて上げられない場合と、自作チャネルの短い実装例としてserver.tsを読みたい場合くらいです。 両方を同時に動かすのは避けてください。[Issue #6](https://github.com/louislva/claude-peers-mcp/issues/6)（2026年3月23日）では、ピアへの返信でClaudeがclaude-peersの `send_message` ではなく、Agent Teams用の組み込み `SendMessage` を選び、メッセージが相手に届かない現象が報告されています。公式セッション間メッセージが入る前の報告ですが、似た役割の送信ツールが2つ並ぶ状況は今も同じです。乗り換えるならclaude-peersは外しておくのが確実で、手順は次のとおりです。 ``` claude mcp remove claude-peers --scope user cd ~/claude-peers-mcp && bun cli.ts kill-broker rm -f ~/.claude-peers.db ~/.claude-peers.db-wal ~/.claude-peers.db-shm ``` DBはWALモードなので、`-wal` と `-shm` のファイルも消します。続けてcloneしたディレクトリを削除し、起動エイリアスから `--dangerously-load-development-channels server:claude-peers` を外してください。Claude Codeを再起動して `/list-agents` にほかのセッションが出れば、移行は完了です。 ## Claude Codeの複数セッション連携とAgent Teams・サブエージェントの使い分け 公式の[並列実行の整理ページ](https://code.claude.com/docs/en/agents)は、複数のClaudeを動かす方法を「誰が作業を取りまとめるか」で分けています。セッション間メッセージは独立した方式ではなく、自分で起動したセッション同士が発見や状況を渡すための補助機能という位置づけです。 | 方式 | 取りまとめ役 | 結果の行き先 | 状態 | | ----------- | ---------- | -------------- | --------- | | サブエージェント | メインのClaude | 呼び出した会話 | 正式機能 | | agent view | あなた | あなた | リサーチプレビュー | | Agent Teams | リードのClaude | チーム内で相互に連絡 | 実験的・既定オフ | | セッション間メッセージ | （補助機能） | 自分で起動したセッション同士 | 既定オン | [サブエージェント](/tech/details/7911/)は、1つの会話の中で調査やレビューを切り出し、要約だけを戻します。[Agent Teams](/tech/details/10960/)は `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` で有効にする実験的機能で、リードが仲間を起動して分担させます。公式ドキュメントは1セッションより大幅に多くトークンを使うと明記しています。agent viewは `claude agents` で開き、バックグラウンドのセッションを1画面で起動・監視します。 判断は単純です。1つの作業を分解して並列にしたいならサブエージェントかAgent Teams。自分で別々に始めたセッション同士で、途中の発見や変更を伝えたいならセッション間メッセージです。同じファイルを触る並列作業ならworktreeで分けます。社内の開発フローにこうした複数エージェントの構成を組み込む場合は、[AIエージェント開発の支援](/service/ai/agent/)で設計から相談を受け付けています。 ## claude-peers-mcpのよくある質問 ### claude-peers-mcpとは何ですか？ 同じPC上の複数のClaude Codeセッションが互いを一覧し、メッセージを送り合えるようにするOSSのMCPサーバーです。MITライセンスで、localhostのブローカーとSQLiteで中継し、Channels機能で受信側の会話に差し込みます。2026年8月以降は、Claude Code本体のセッション間メッセージで同じことができます。 ### dangerously-load-development-channelsは何をするフラグですか？ Anthropicの許可リストに無いチャネルを、指定した項目に限って読み込ませる開発者向けのフラグです。claude-peersはリストに無いため、`server:claude-peers` を指定してこのフラグで起動します。起動時に確認プロンプトが出て、`claude --help` には表示されません。Team・Enterpriseで `channelsEnabled` が無効なら、このフラグでも届きません。 ### Claude ConsoleのAPIキー認証でも使えますか？ 使えます。Channelsはv2.1.128（2026年5月4日）からConsoleのAPIキー認証に対応しており、READMEの「APIキーでは動かない」はそれ以前の記述です。Bedrock・Agent Platform・Foundry経由では使えません。公式のセッション間メッセージは、同じPC内ならこれらの経路でもv2.1.248以上で使えます。 ### 同じアカウントでClaude Codeを同時に複数起動できますか？ できます。同じアカウントで複数のセッションを並べて動かせて、v2.1.224以上ならセッション同士で連絡も取れます。ただし公式ドキュメントのとおり、同時に動かすセッション数に応じてトークンの使用量が増え、プランの上限に早く届きます。プランごとの上限は[Claude Codeの料金プランと使用上限の比較](/tech/details/17988/)を参照してください。 ### Agent TeamsとMCPのclaude-peersは何が違いますか？ Agent Teamsは、リードのセッションが仲間のClaudeを起動して分担させる公式の実験的機能です。claude-peersは、あなたが別々に起動した独立したセッションをつなぐだけで、タスクの管理はしません。分担させるならAgent Teams、別々のプロジェクトの間で連絡を取るなら公式のセッション間メッセージが向いています。 ## 関連記事 - [Claude Code Agent Teamsとは？使い方・設定・料金とサブエージェントとの違い](/tech/details/10960/) - [Claude Codeのgit worktreeで並列エージェント開発を行う方法｜仕組み・使い方・注意点【2026年版】](/tech/details/11708/) - [Claude Codeのサブエージェントとは？作り方・設定項目・使い方【v2.1.287対応】](/tech/details/7911/) - [Discord MCPの使い方｜Claude Code公式プラグインとMCPサーバーの選び方・設定手順【2026年10月】](/tech/details/8360/) - [Claude Codeのパーミッションモードの違いと設定方法｜auto・acceptEdits・bypassPermissionsの使い分け](/tech/details/11246/) --- 出典: [claude-peers-mcpとは？仕組み・導入手順と公式セッション間メッセージとの違い]()（株式会社一創）