Back to Details

claude-peers-mcp

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

claude-peers-mcp

claude-peers-mcp

Skill by ara.so — Daily 2026 Skills collection.
claude-peers is an MCP server that lets multiple Claude Code instances running on the same machine discover each other and exchange messages in real-time. A local broker daemon (SQLite + HTTP on 
localhost:7899
) handles peer registration and message routing; each session's MCP server pushes inbound messages directly into the Claude channel so they appear instantly.
由ara.so开发的Skill — 2026每日技能合集。
claude-peers是一个MCP服务器，可让同一台机器上运行的多个Claude Code实例互相发现并实时交换消息。本地代理守护进程（SQLite + HTTP，运行在
localhost:7899
）处理节点注册和消息路由；每个会话的MCP服务器会将入站消息直接推送到Claude频道，使其即时显示。

Installation

安装

1. Clone and install dependencies

1. 克隆仓库并安装依赖

bash
git clone https://github.com/louislva/claude-peers-mcp.git ~/claude-peers-mcp
cd ~/claude-peers-mcp
bun install
bash
git clone https://github.com/louislva/claude-peers-mcp.git ~/claude-peers-mcp
cd ~/claude-peers-mcp
bun install

2. Register as a global MCP server

2. 注册为全局MCP服务器

bash
claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts
Adjust the path if you cloned elsewhere.
bash
claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts
如果克隆到了其他路径，请调整上述路径。

3. Launch Claude Code with the channel enabled

3. 启用频道功能启动Claude Code

bash
claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers
Add a shell alias to avoid typing it every time:
bash
undefined
bash
claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers
可以添加Shell别名，避免每次重复输入：
bash
undefined

~/.bashrc or ~/.zshrc

~/.bashrc 或 ~/.zshrc

alias claudepeers='claude --dangerously-load-development-channels server:claude-peers'

The broker daemon starts automatically on first use. No manual daemon management needed.
alias claudepeers='claude --dangerously-load-development-channels server:claude-peers'

代理守护进程会在首次使用时自动启动，无需手动管理。

Requirements

环境要求

  • Bun runtime
  • Claude Code v2.1.80+
  • claude.ai login (channels require it — API key auth does not work)
  • Bun 运行时
  • Claude Code v2.1.80+
  • claude.ai登录（频道功能需要该登录方式，API密钥认证无法使用）

Architecture

架构

                    ┌───────────────────────────┐
                    │  broker daemon            │
                    │  localhost:7899 + SQLite  │
                    └──────┬───────────────┬────┘
                           │               │
                      MCP server A    MCP server B
                      (stdio)         (stdio)
                           │               │
                      Claude A         Claude B
  • Each Claude Code session spawns its own 
    server.ts
    MCP process over stdio
  • MCP servers register with the broker and poll every second
  • Inbound messages are pushed via the 
    claude/channel
    protocol for instant delivery
  • The broker auto-cleans dead peers and is localhost-only
                    ┌───────────────────────────┐
                    │  broker daemon            │
                    │  localhost:7899 + SQLite  │
                    └──────┬───────────────┬────┘
                           │               │
                      MCP server A    MCP server B
                      (stdio)         (stdio)
                           │               │
                      Claude A         Claude B
  • 每个Claude Code会话都会通过stdio启动自己的
    server.ts
    MCP进程
  • MCP服务器会向代理注册，并每秒轮询一次
  • 入站消息通过
    claude/channel
    协议推送，实现即时送达
  • 代理会自动清理失效节点，且仅在本地主机运行

MCP Tools Reference

MCP工具参考

ToolDescription
list_peers
Discover other Claude Code instances; scope: 
machine
, 
directory
, or 
repo
send_message
Send a message to a peer by ID — delivered instantly via channel push
set_summary
Set a description of what this instance is working on
check_messages
Manually poll for messages (fallback without channel mode)
工具描述
list_peers
发现其他Claude Code实例；范围可选：
machine
（机器）、
directory
（目录）或
repo
（仓库）
send_message
通过ID向指定节点发送消息 — 频道推送实现即时送达
set_summary
设置当前实例的工作描述
check_messages
手动轮询消息（无频道模式时的备选方案）

Example prompts to Claude

向Claude发送的示例提示

List all peers on this machine
Send a message to peer abc123: "what files are you editing right now?"
Set your summary to: "refactoring the authentication module"
Check for any new messages from peers
列出这台机器上的所有节点
向节点abc123发送消息："你现在正在编辑哪些文件？"
将你的工作描述设置为："重构认证模块"
检查是否有来自其他节点的新消息

CLI Usage

CLI使用方法

Inspect and interact with the broker directly from the terminal:
bash
cd ~/claude-peers-mcp
直接从终端检查并与代理交互：
bash
cd ~/claude-peers-mcp

Show broker status and all registered peers

查看代理状态和所有已注册节点

bun cli.ts status
bun cli.ts status

List peers in a table

以表格形式列出节点

bun cli.ts peers
bun cli.ts peers

Send a message into a specific Claude session

向特定Claude会话发送消息

bun cli.ts send <peer-id> "your message here"
bun cli.ts send <peer-id> "你的消息内容"

Stop the broker daemon

停止代理守护进程

bun cli.ts kill-broker
undefined
bun cli.ts kill-broker
undefined

Configuration

配置

Set these environment variables before starting Claude Code:
VariableDefaultDescription
CLAUDE_PEERS_PORT
7899
Port the broker listens on
CLAUDE_PEERS_DB
~/.claude-peers.db
Path to the SQLite database
OPENAI_API_KEY
—Enables auto-summary via 
gpt-4o-mini
on startup
bash
export CLAUDE_PEERS_PORT=7899
export CLAUDE_PEERS_DB=~/.claude-peers.db
export OPENAI_API_KEY=$OPENAI_API_KEY  # optional — enables auto-summary
启动Claude Code前设置以下环境变量：
变量默认值描述
CLAUDE_PEERS_PORT
7899
代理监听的端口
CLAUDE_PEERS_DB
~/.claude-peers.db
SQLite数据库的路径
OPENAI_API_KEY
—启用启动时通过
gpt-4o-mini
自动生成摘要的功能
bash
export CLAUDE_PEERS_PORT=7899
export CLAUDE_PEERS_DB=~/.claude-peers.db
export OPENAI_API_KEY=$OPENAI_API_KEY  # 可选 — 启用自动摘要功能

Auto-Summary Feature

自动摘要功能

With 
OPENAI_API_KEY
set, each instance generates a brief summary on startup describing what you're likely working on (based on working directory, git branch, recent files). Other peers see this in 
list_peers
output. Without the key, Claude sets its own summary via 
set_summary
.
设置
OPENAI_API_KEY
后，每个实例在启动时会生成一个简短摘要，描述你当前可能正在进行的工作（基于工作目录、Git分支、最近操作的文件）。其他节点可在
list_peers
的输出中看到该摘要。如果未设置密钥，可通过
set_summary
让Claude自行设置摘要。

Common Patterns

常见使用场景

Cross-project coordination

跨项目协作

Start two sessions in different project directories:
bash
undefined
在不同项目目录中启动两个会话：
bash
undefined

Terminal 1 — in ~/projects/backend

终端1 — 位于~/projects/backend

claudepeers
claudepeers

Terminal 2 — in ~/projects/frontend

终端2 — 位于~/projects/frontend

claudepeers

Ask Claude in Terminal 1:
List peers scoped to machine, then ask the peer in the frontend project what API endpoints it needs
undefined
claudepeers

在终端1中询问Claude：
列出机器范围内的所有节点，然后询问前端项目中的节点需要哪些API接口
undefined

Scope-filtered peer discovery

范围过滤的节点发现

List peers scoped to repo
Shows only instances running in the same git repository — useful when you have worktrees or split terminals on the same codebase.
列出仓库范围内的节点
仅显示在同一Git仓库中运行的实例 — 当你在同一代码库中使用工作树或拆分终端时非常有用。

Scripted message injection via CLI

通过CLI脚本注入消息

bash
undefined
bash
undefined

Inject a task into a running Claude session from a shell script

从Shell脚本向运行中的Claude会话注入任务

PEER_ID=$(bun ~/claude-peers-mcp/cli.ts peers | grep 'backend' | awk '{print $1}') bun ~/claude-peers-mcp/cli.ts send "$PEER_ID" "run the test suite and report failures"
undefined
PEER_ID=$(bun ~/claude-peers-mcp/cli.ts peers | grep 'backend' | awk '{print $1}') bun ~/claude-peers-mcp/cli.ts send "$PEER_ID" "运行测试套件并报告失败情况"
undefined

Polling fallback (no channel mode)

轮询备选方案（无频道模式）

If you launch without 
--dangerously-load-development-channels
, Claude can still receive messages by calling 
check_messages
explicitly:
Check for any new peer messages
如果启动时未添加
--dangerously-load-development-channels
参数，Claude仍可通过显式调用
check_messages
来接收消息：
检查是否有新的节点消息

Troubleshooting

故障排除

Broker not starting
bash
undefined
代理无法启动
bash
undefined

Check if something is already on port 7899

检查端口7899是否被占用

lsof -i :7899
lsof -i :7899

Kill a stuck broker and restart

终止卡住的代理并重启

bun ~/claude-peers-mcp/cli.ts kill-broker
bun ~/claude-peers-mcp/cli.ts kill-broker

Then relaunch Claude Code

然后重新启动Claude Code


**Peers not appearing in `list_peers`**
- Ensure both sessions were started with `--dangerously-load-development-channels server:claude-peers`
- Confirm both use the same `CLAUDE_PEERS_PORT` (default `7899`)
- Run `bun cli.ts status` to verify the broker sees both registrations

**Messages not arriving instantly**
- Channel push requires claude.ai login; API key auth won't work
- Fall back to `check_messages` tool if channels are unavailable

**Auto-summary not generating**
- Verify `OPENAI_API_KEY` is exported in the shell where Claude Code was launched: `echo $OPENAI_API_KEY`
- The feature uses `gpt-4o-mini`; confirm your key has access

**Database issues**
```bash

**`list_peers`中看不到节点**
- 确保两个会话都使用`--dangerously-load-development-channels server:claude-peers`启动
- 确认两者使用相同的`CLAUDE_PEERS_PORT`（默认7899）
- 运行`bun cli.ts status`验证代理是否已注册两个实例

**消息无法即时送达**
- 频道推送需要claude.ai登录；API密钥认证无效
- 如果频道不可用，可使用`check_messages`工具作为备选

**自动摘要无法生成**
- 验证启动Claude Code的Shell中是否已导出`OPENAI_API_KEY`：`echo $OPENAI_API_KEY`
- 该功能使用`gpt-4o-mini`；请确认你的密钥有权限访问该模型

**数据库问题**
```bash

Reset the database entirely (all peers/messages lost)

完全重置数据库（所有节点/消息将丢失）

rm ~/.claude-peers.db bun ~/claude-peers-mcp/cli.ts kill-broker

**MCP server not found after registration**
```bash
rm ~/.claude-peers.db bun ~/claude-peers-mcp/cli.ts kill-broker

**注册后找不到MCP服务器**
```bash

Verify registration

验证注册状态

claude mcp list
claude mcp list

Re-register if missing

如果丢失则重新注册

claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts
undefined
claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts
undefined