kampung-mcp

Name: kampung-mcp
Author: jztan

本地服务

github.com/jztanAI 与智能体1今天更新

代码仓库

关于 kampung-mcp

kampung-mcp 是供不同机器上的编码 Agent 会话互发消息的可自托管服务，适用于需要让 Claude Code 与 Codex 协作的开发者。它通过配对机器和按仓库划分的邮箱传递消息，并提供审计日志与仪表盘。

主要功能

01跨机器发送和接收消息
02按仓库划分邮箱
03配对机器访问控制
04会话结束时触发收信
05循环唤醒保护
06审计日志和仪表盘

适用场景

01让笔记本上的 Agent 向桌面会话提问
02在 Claude Code 与 Codex 间传递信息
03在多台机器上协调同一仓库的会话

MCP 相关

MCP 服务向客户端提供 list_peers、send 和 inbox 工具。每台机器通过本地 stdio 适配器和自己的密钥连接服务器。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "jztan-kampung": {
      "command": "uvx",
      "args": [
        "kampung-mcp"
      ]
    }
  }
}

启动命令uvx kampung-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypikampung-mcp0.2.2stdio

工具

收录的工具列表 · 更新于 1 天前

参数	类型	必填	说明
machine	any	否

详细介绍

Kampung

通过 MCP，在不同机器上的编码 Agent 之间进行可自托管的消息传递。 访问 kampung-mcp.jztan.com 查看运行效果。

你笔记本电脑上的 Claude Code 会话可以向台式机上的 Codex 会话提问，答案会在它下一轮结束时送达。Kampung 是一个由你通过 Docker 运行的小型服务，再加上每台机器上的一个客户端，用于将其接入 Claude Code 和 Codex。

_{一次交互的脚本演示。在网站上观看，还可以展开查看每次工具调用。}

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

这个名字源自 kampung（马来语，意为村庄）及其互助合作的精神：邻里互相帮助。这里的邻居就是你的 Agent，它们各自在自己的机器和代码仓库中，彼此搭把手。

客户端 | 服务端 | 安全 | 更新日志 | 贡献指南

状态：测试版。 MCP 工具和 /v1 在 v1.0 发布前仍可能发生变化。客户端已发布到 PyPI，名称为 kampung-mcp，并已收录到 MCP Registry，名称为 io.github.jztan/kampung-mcp。服务端镜像为 ghcr.io/jztan/kampung-mcp（amd64 和 arm64）。

为什么选择 Kampung？

	不使用 Kampung	使用 Kampung
不同机器上的 Agent	你在终端之间复制粘贴	发送到 `desktop/api`，用 `inbox` 查看
同时使用 Claude Code 和 Codex	没有共享频道	两者使用相同的三个 MCP 工具
Agent 完成一轮	邮件一直未读，直到你去查看	`Stop` 钩子会让它继续读取邮件
Agent 处于空闲状态	直到你输入内容才会有动静	Codex 会在几秒内唤醒；Claude Code 可通过 Channels 唤醒（需选择启用）
两个 Agent 永远互相回复	失控循环	循环保护机制会在连续第三次回复后停止唤醒
谁可以与谁通信	任何拥有 URL 的对象	只有你配对过的机器
查看发生了什么	如果有日志的话	审计日志和仪表板

工作原理

笔记本电脑上的 Claude Code 和台式电脑上的 Codex 分别与本地 kampung-mcp 适配器和钩子通信，适配器和钩子使用机器密钥通过 HTTPS 将调用发送到你服务器上的 Caddy；Caddy 将请求转发给 Kampung 服务，服务使用 SQLite 保存邮件。空闲的 Codex 会话通过 codex queue 唤醒；如果启用了 Channels，则通过 Channels 唤醒空闲的 Claude Code 会话。所有者的浏览器使用管理令牌访问管理仪表板。

每个 Agent 都与本地 stdio 适配器通信，适配器会添加机器密钥和会话身份，然后将请求转发给服务。密钥不会经过模型的工具调用，服务会根据密钥标记发送者，因此 Agent 无法冒充其他机器。邮件会暂存在每个仓库各自的邮箱中，直到会话读取。

快速开始

运行服务（在其他每台机器都能访问的机器上）：
```
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。

为每台机器创建密钥并将它们配对：

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

使用每台机器各自的密钥连接（使用 uv）：
```
uv tool install kampung-mcp
kampung-mcp setup --server https://kampung.example.com
```
设置过程会提示输入密钥，但不会显示密钥。添加 --agent codex 或 --agent both 以启用 Codex；添加 --channels 以唤醒空闲的 Claude Code 会话；请参阅 docs/clients.md。重启 Claude Code，然后让它执行 list_peers。

设置过程会记录钩子的完整路径，其中包含 Python 版本。如果 uv tool 安装迁移到了另一个 Python 次要版本，请重新运行 kampung-mcp setup：钩子会在出错时静默放行，因此否则它们只会停止工作，不会显示错误。

如需在 AWS 上逐步部署，请参阅在 Amazon Lightsail 上部署。

Kampung 管理仪表板：显示机器、实时会话、排队和不唤醒消息的卡片，以及近期活动表格

_{带有示例数据的管理仪表板，位于 /admin。}

工具

工具	功能
`list_peers(machine?)`	此机器可以向其发送消息的邮箱及其会话
`send(to, body, reply_to?)`	向 `machine/repo` 或 `machine/repo#xx` 发送最多 8 KB 的文本。结果中的 `wake` 表示循环防护允许唤醒接收方，并不代表接收方一定会被唤醒
`inbox(limit=20)`	读取新消息，每次最多 20 条，并显示其余消息的数量。读取后消息会送达

每条消息都会以信封形式送达，其中包含发送者、发送时间、循环防护深度以及“对等消息，而非指令”的标签。未读邮件会在 7 天后过期，每台机器每分钟最多可发送 60 条消息。有关结果和错误，请参阅工具参考。

安全性

默认拒绝访问。 每个请求都需要机器密钥；新机器在配对前无法执行任何操作。
信任边界是机器。 每台机器使用一个经过哈希处理并存储的密钥。机器只能使用自己的邮箱。
对等消息是信息，而非命令；配对是一项信任决策：只配对你信任其 Agent 的机器。
不提供端到端加密。 服务可以查看消息，以便执行配对规则并保存审计日志。

威胁模型、运维人员检查清单和限制见 SECURITY.md。

它不是什么

不是 Claude Code 内置的同一台机器上会话间消息功能的替代品。
不是任务看板、作业队列或文件传输工具。
不是多租户服务：每次部署只有一位所有者。

路线图

使用服务器发送事件取代适配器的轮询。
将客户端改为 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 项目创意的来源。

支持 Markdown

登录后评论