claude-peers: 여러 Claude Code 인스턴스가 서로 메시지를 주고받는 MCP 서버

9bow · 6월 21, 2026, 7:30오전

claude-peers 소개

claude-peers는 같은 컴퓨터에서 실행 중인 여러 Claude Code 인스턴스가 서로를 발견하고 메시지를 주고받게 해 주는 MCP 서버입니다. 서로 다른 프로젝트에서 다섯 개의 세션을 띄워 작업할 때, 각 Claude가 다른 세션을 찾아 즉시 메시지를 보낼 수 있습니다. 한쪽 터미널에서 "어떤 파일을 편집하고 있어?"라고 물으면 다른 세션의 Claude가 그 메시지를 바로 받아 응답하는 식입니다.

여러 세션을 동시에 돌리다 보면 각 세션이 서로 무엇을 하는지 알지 못한 채 따로 작업하게 됩니다. claude-peers는 이렇게 흩어진 세션들을 하나의 로컬 네트워크로 묶어, 세션끼리 진행 상황을 공유하고 작업을 조율할 수 있는 통로를 만들어 줍니다. 모든 통신은 localhost 안에서만 이루어집니다.

claude-peers는 MIT 라이선스로 공개되어 있으며, 실행에는 Bun과 Claude Code v2.1.80 이상이 필요합니다. 채널(channel) 기능을 사용하므로 claude.ai 로그인이 있어야 하고, API 키 인증만으로는 동작하지 않습니다. 본 게시물에서는 claude-peers의 동작 구조와 Claude가 사용할 수 있는 도구, 설치 방법을 정리합니다.

claude-peers의 동작 구조

claude-peers의 중심에는 localhost:7899 에서 SQLite 데이터베이스와 함께 동작하는 브로커 데몬(broker daemon)이 있습니다. 각 Claude Code 세션은 MCP 서버를 띄워 브로커에 자신을 등록하고 1초마다 메시지를 폴링합니다. 들어온 메시지는 claude/channel 프로토콜을 통해 세션으로 푸시되므로, Claude가 메시지를 즉시 인식합니다.

브로커 데몬은 첫 세션이 시작될 때 자동으로 실행되며, 응답이 없는 죽은 피어(peer)를 알아서 정리합니다. 모든 구성 요소가 localhost에서만 동작하므로 외부로 트래픽이 나가지 않습니다.

claude-peers가 제공하는 도구

claude-peers를 등록하면 Claude는 다른 세션과 상호작용하는 네 가지 도구를 쓸 수 있습니다. list_peers 는 다른 Claude Code 인스턴스를 찾되 머신(machine), 디렉토리(directory), 저장소(repo) 범위로 좁혀 조회합니다. send_message 는 인스턴스 ID로 메시지를 보내며, 채널 푸시를 통해 즉시 전달됩니다. set_summary 는 지금 어떤 작업을 하고 있는지 다른 피어가 볼 수 있도록 설명을 남기고, check_messages 는 채널 모드를 쓰지 않을 때 수동으로 메시지를 확인하는 대비책입니다.

각 인스턴스는 시작할 때 자신이 무엇을 하고 있는지에 대한 요약을 남깁니다. 환경에 OPENAI_API_KEY 가 설정되어 있으면 디렉토리와 git 브랜치, 최근 파일을 바탕으로 gpt-5.4-nano 가 짧은 요약을 자동으로 생성하며, 키가 없으면 Claude가 set_summary 도구로 직접 요약을 설정합니다. 이 요약은 다른 인스턴스가 list_peers 를 호출할 때 함께 표시됩니다.

claude-peers 설치 및 사용법

먼저 저장소를 받아 의존성을 설치한 뒤, MCP 서버를 사용자 범위로 등록합니다. 등록하면 어느 디렉토리에서 실행하든 모든 Claude Code 세션에서 claude-peers를 사용할 수 있습니다.

# 1. 설치
git clone https://github.com/louislva/claude-peers-mcp.git ~/claude-peers-mcp
cd ~/claude-peers-mcp
bun install

# 2. MCP 서버 등록
claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts

이후 두 개의 터미널에서 Claude Code를 실행하고, 한쪽에 "이 머신의 모든 피어를 보여줘"라고 요청하면 실행 중인 인스턴스 목록이 작업 디렉토리, git 저장소, 작업 요약과 함께 표시됩니다. 명령줄에서 직접 상태를 확인하거나 메시지를 보낼 수도 있습니다.

bun cli.ts status            # 브로커 상태 + 전체 피어
bun cli.ts peers             # 피어 목록
bun cli.ts send <id> <msg>   # 특정 Claude 세션으로 메시지 전송
bun cli.ts kill-broker       # 브로커 중지

브로커 포트(CLAUDE_PEERS_PORT, 기본값 7899)와 SQLite 데이터베이스 경로(CLAUDE_PEERS_DB, 기본값 ~/.claude-peers.db)는 환경 변수로 바꿀 수 있습니다.

claude-peers의 라이선스

claude-peers는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

claude-peers 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~