Context Vault

Claude Peers MCP - Claude Code 인스턴스 간 실시간 통신

4 min read

Claude Peers MCP - Claude Code 인스턴스 간 실시간 통신

여러 Claude Code 세션이 서로 발견하고 실시간으로 메시지를 주고받는 MCP 서버. 사전 설정 없이 자연스러운 에이전트 간 협업 가능.

핵심 요약

  • Ad-hoc 에이전트 통신 — 여러 Claude Code 세션이 서로 직접 메시지 교환
  • 실시간 채널 푸시 — 메시지가 즉시 도착 (channel 프로토콜 사용)
  • 자동 발견 — 같은 머신의 다른 인스턴스 자동 감지
  • 요약 자동 생성 — GPT-5.4-nano로 작업 중인 내용 요약 (선택)

사용 시나리오

시나리오설명
API + 프론트 협업한 에이전트는 API 개발, 다른 에이전트는 프론트 개발 → 인터페이스 자동 조율
멀티 프로젝트5개 세션이 서로 다른 프로젝트 작업 중 → 서로 상태 확인 및 조율
코드 리뷰한 에이전트가 작성, 다른 에이전트가 리뷰

아키텍처

┌───────────────────────────┐
│   broker daemon           │
│   localhost:7899 + SQLite │
└──────┬───────────────┬────┘
       │               │
   MCP server A    MCP server B
    (stdio)          (stdio)
       │               │
   Claude A         Claude B
  • Broker daemon — localhost:7899에서 실행, SQLite로 메시지 관리
  • 자동 시작 — 첫 세션 시작 시 자동 실행
  • 자동 정리 — 죽은 피어 자동 제거
  • 로컬 전용 — 모든 통신 localhost만

MCP 도구

도구기능
list_peers다른 Claude Code 인스턴스 목록 (머신/디렉토리/레포 범위)
send_message특정 인스턴스에 메시지 전송 (즉시 도착)
set_summary작업 중인 내용 설명 (다른 피어에 표시)
check_messages수동 메시지 확인 (채널 모드 미사용 시)

설치 및 실행

# 클론
git clone https://github.com/louislva/claude-peers-mcp.git ~/claude-peers-mcp
cd ~/claude-peers-mcp
bun install
 
# MCP 등록 (전역)
claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts
 
# Claude Code 실행 (채널 활성화)
claude --dangerously-load-development-channels server:claude-peers

Alias 설정:

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

사용 예시

피어 목록 조회:

List all peers on this machine

메시지 전송:

Send a message to peer [id]: "what are you working on?"

CLI 명령어

cd ~/claude-peers-mcp
 
bun cli.ts status       # 브로커 상태 + 모든 피어
bun cli.ts peers        # 피어 목록
bun cli.ts send <id> <msg>  # 메시지 전송
bun cli.ts kill-broker  # 브로커 중지

환경 변수

변수기본값설명
CLAUDE_PEERS_PORT7899브로커 포트
CLAUDE_PEERS_DB~/.claude-peers.dbSQLite 경로
OPENAI_API_KEY—자동 요약 활성화 (gpt-5.4-nano)

기존 Agent Teams와 차이점

구분Agent TeamsClaude Peers
설정사전 설정 필요Ad-hoc (설정 없음)
통신오케스트레이터 경유직접 P2P
유연성고정 역할동적 협업
진입 장벽높음낮음 (설치 후 바로 사용)

요구 사항

  • Bun
  • Claude Code v2.1.80+
  • claude.ai 로그인 (채널 사용 — API 키 인증 불가)

관련 노트

Sources

그래프 뷰