Phone A Friend MCP

🚀 Phone-a-Friend MCP

An MCP server that enables real-time communication between Claude Code instances. One instance enters "listening mode", while another initiates contact with a specific intent.

🚀 Quick Start

The Phone - a - Friend MCP is an MCP server designed to facilitate real - time communication between Claude Code instances. One instance can act as a listener, and another can initiate contact with a specific purpose.

✨ Features

• Enables real - time communication between Claude Code instances.
• Allows one instance to enter "listening mode" and another to initiate contact with a specific intent.

📦 Installation

cd ~/.claude/mcps/phone-a-friend
pip install -e .

💻 Usage Examples

Basic Usage

Step 1: Start the Hub

paf-hub

Step 2: Configure Claude Code

Add the following to ~/.claude/settings.json:

{
  "mcpServers": {
    "phone-a-friend": {
      "command": "python",
      "args": ["-m", "phone_a_friend.server"],
      "cwd": "/Users/YOUR_USERNAME/.claude/mcps/phone-a-friend/src"
    }
  }
}

Step 3: Use It

Tab 1 (Listener):

"Listen for questions. You're the auth expert."

→ paf(action="listen", session_name="auth-expert", description="Expert on auth") → Blocks waiting...

Tab 2 (Caller):

"Ask the auth expert about token refresh."

→ paf(action="list_sessions") → sees "auth-expert" → paf(action="connect", target_session="auth-expert", intent="Token refresh", my_name="feature-dev") → paf(action="send", target_session="auth-expert", message="How handle expired tokens?", my_name="feature-dev") → paf(action="wait_response", my_name="feature-dev") → blocks for answer

Tab 1 receives, responds: → Listener unblocks with question → paf(action="respond", session_name="auth-expert", message="Use sliding window...") → paf(action="listen", ...) → back to waiting

📚 Documentation

Tool Reference

Single tool paf with actions:

Conversation Flow

Listener                              Caller
────────                              ──────
listen() [blocks]
                                      connect(intent)
                                      send(question)
[receives question]
respond(answer)
                                      wait_response() → answer
listen() [blocks]                     send(follow_up)
[receives follow_up]
...

🔧 Technical Details

┌─────────────────────────────────────────┐
│      paf-hub (TCP server)               │
│      localhost:7777                     │
└─────────────────────────────────────────┘
         ▲                    ▲
         │ TCP                │ TCP
         │                    │
   Claude Tab 1          Claude Tab 2
   (Listener)            (Caller)