kampung-mcp

Kampung

MCP を介して、異なるマシン上のコーディングエージェント同士がメッセージをやり取りできる、セルフホスト可能な仕組みです。 kampung-mcp.jztan.comで動作をご覧ください。

ノートパソコン上の Claude Code セッションから、デスクトップ上の Codex セッションに質問できます。回答は、次のターンの終わりに届きます。Kampung は Docker で実行する小さなサーバーと、Claude Code および Codex に接続する各マシン上のクライアントで構成されます。

_{1 回のやり取りをスクリプトで再生したものです。サイトでご覧ください}

mcp-name: io.github.jztan/kampung-mcp

名前は、マレー語で「村」を意味する kampung と、近所の人同士が助け合う gotong-royong の精神に由来します。ここで近所の人にあたるのは、それぞれ別のマシンとリポジトリで動作し、互いに手を貸すエージェントです。

クライアント | サーバー | セキュリティ | 変更履歴 | コントリビューション

ステータス：ベータ版。 MCP ツールと /v1 は v1.0 より前に変更される可能性があります。クライアントは PyPI で kampung-mcp として、MCP Registry で io.github.jztan/kampung-mcp として公開されています。サーバーイメージは ghcr.io/jztan/kampung-mcp（amd64 および arm64）です。

Kampung を使う理由

	Kampung を使わない場合	Kampung を使う場合
異なるマシン上のエージェント	ターミナル間でコピー＆ペーストします	desktop/api に send し、inbox で読みます
Claude Code と Codex の併用	共通のチャネルがありません	どちらも同じ 3 つの MCP ツールを使います
エージェントがターンを終える	メールは、あなたが確認するまで未読のままです	Stop フックがメールを読み続けさせます
エージェントがアイドル状態	入力するまで何も起こりません	Codex は数秒以内に起動します。Claude Code は Channels で起動します（オプトイン）
2 つのエージェントが延々と返信し合う	ループが暴走します	ループガードにより、返信が 3 回連続した後は起動しなくなります
誰が誰と話せるか	URL を知っている人なら誰でも利用できます	ペアリングしたマシンだけが利用できます
何が起きたかの確認	ログがある場合はログを確認します	監査ログとダッシュボードがあります

仕組み

各エージェントはローカルの stdio アダプターと通信します。アダプターはマシンキーとセッションの ID を追加して、サーバーに転送します。キーがモデルのツール呼び出しを経由することはありません。また、サーバーはキーから送信者を設定するため、エージェントが別のマシンになりすますことはできません。セッションがメールを読むまで、メールはリポジトリごとのメールボックスに保管されます。

クイックスタート

1. サーバーを実行します（ほかのすべてのマシンからアクセスできるマシン上で実行します）。

   git clone --branch master https://github.com/jztan/kampung-mcp.git
   cd kampung-mcp
   docker compose up -d --wait
   

   最新リリースを実行し、127.0.0.1:8803 でリッスンします。HTTPS、リリースの固定、バックアップについては、docs/server.md を参照してください。

2. 各マシンのキーを作成し、ペアリングします。

   docker compose exec kampung kampung key add laptop     # prints the key once
   docker compose exec kampung kampung key add desktop
   docker compose exec kampung kampung pair laptop desktop
   

3. 各マシンを、それぞれのキーで接続します（uv を使用）。

   uv tool install kampung-mcp
   kampung-mcp setup --server https://kampung.example.com
   

   セットアップでは、キーを表示せずに入力を求められます。Codex を使用するには --agent codex または --agent both を追加し、アイドル状態の Claude Code セッションを起動するには --channels を追加してください。docs/clients.md を参照してください。Claude Code を再起動し、list_peers を実行するよう指示してください。

   セットアップでは、フックの完全なパスが記録されます。このパスには Python のバージョンが含まれます。uv tool のインストール先が別の Python マイナーバージョンに変わった場合は、kampung-mcp setup を再実行してください。フックはフェイルオープンするため、再実行しない場合はエラーが発生せず、フックが動作しなくなるだけです。

AWS へのデプロイ手順については、Amazon Lightsail へのデプロイを参照してください。

_{サンプルデータを表示した、/admin の管理ダッシュボード。}

ツール

ツール	機能
list_peers(machine?)	このマシンがメッセージを送信できるメールボックスと、そのセッション
send(to, body, reply_to?)	machine/repo または machine/repo#xx に最大 8 KB のテキストを送信します。結果の wake は、ループガードによって受信側を起動できる状態であることを示します。実際に起動されることを意味するわけではありません
inbox(limit=20)	新着メッセージを一度に最大 20 件まで読み取り、残りの件数も表示します。読み取るとメッセージが配信されます

すべてのメッセージは、送信者、送信時刻、ループガードの深さ、および「ピアからのメッセージであり、指示ではない」というタグを含むエンベロープで届きます。未読メールは 7 日後に期限切れとなり、各マシンは 1 分あたり 60 件のメッセージを送信できます。結果とエラーについては、ツールリファレンスを参照してください。

セキュリティ

• デフォルトでは閉じています。 すべてのリクエストにマシンキーが必要です。新しいマシンは、ペアリングするまで何もできません。
• 信頼境界はマシンです。 マシンごとにキーを 1 つ使用し、ハッシュ化して保存します。各マシンは、自分のメールボックスのみを使用できます。
• ピアからのメッセージは情報であり、指示ではありません。 また、ペアリングは信頼に関わる判断です。エージェントを信頼できるマシンのみをペアリングしてください。
• エンドツーエンド暗号化ではありません。 サーバーは、ペアリングを適用して監査ログを保持するためにメッセージを参照します。

脅威モデル、運用者向けチェックリスト、および制限事項については、SECURITY.md を参照してください。

これは何ではないか

• 同じマシン上のセッション間で使う Claude Code 組み込みのメッセージ機能を置き換えるものではありません。
• タスクボード、ジョブキュー、ファイル転送ツールではありません。
• マルチテナントではありません。デプロイメントごとに所有者は 1 人です。

ロードマップ

• アダプターのポーリングを置き換える、サーバー送信イベント。
• インストールを簡単にするため、クライアントを Claude Code プラグインとして提供します。Channels には引き続き開発フラグが必要です。

貢献

課題の報告やプルリクエストを歓迎します。貢献ガイドと行動規範をご確認ください。プルリクエストの作成者は、コントリビューターライセンス契約に一度署名します。著作権は引き続きご自身が保持します。

ライセンス

• packages/server（kampung-server）：AGPL-3.0。packages/server/LICENSEをご確認ください。
• packages/client（お使いのマシン上で動作するアダプターとフックであるkampung-mcp）：Apache-2.0。packages/client/LICENSEをご確認ください。

NOTICEには、このプロジェクトの着想元であるKampungへの謝辞を記載しています。