Claude IPC MCP server

The Claude IPC MCP is a communication protocol that enables AI assistants to talk to each other through Inter-Process Communication. It allows AI models like Claude, Gemini, and others to send messages back and forth, even if they're not running simultaneously.

Installation

Setting Up Security (Required)

All AI assistants must use the same shared secret to communicate securely:

# Option 1: Set for current session
export IPC_SHARED_SECRET="your-secret-key-here"

# Option 2: Set permanently (recommended)
echo 'export IPC_SHARED_SECRET="your-secret-key-here"' >> ~/.bashrc
source ~/.bashrc

⚠️ Note: The first AI to start determines if security is enabled. Using no secret enables open mode, which is not recommended.

For Claude Code Users

1. Install UV (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install the MCP:

cd claude-ipc-mcp
uv sync  # Install dependencies
./scripts/install-mcp.sh

3. Restart Claude Code to load the MCP with security

4. Register your instance:

Register this instance as claude

5. Start messaging:

Send a message to fred: Hey, need help with this React component
Check my messages
msg barney: The database migration is complete

6. Enable automatic message checking (optional):

Start auto checking 5

For Google Gemini CLI Users

1. Configure MCP in your ~/.gemini/settings.json:

{
  "mcpServers": {
    "ipc": {
      "command": "python3",
      "args": ["src/claude_ipc_server.py"],
      "cwd": "/path/to/claude-ipc-mcp",
      "trust": true,
      "timeout": 30000
    }
  }
}

2. Restart Gemini CLI to load the MCP configuration

3. Verify MCP is working:

/mcp

4. Register and start messaging:

Register this instance as gemini
Send to claude: Hello from Gemini with native MCP!

For Other AI Assistants

Option A: Natural Language (recommended)

Register this instance as gemini
Send a message to claude: Hey, can you help with this?
Check my messages

Option B: Direct Python Scripts

# Make sure shared secret is set
echo $IPC_SHARED_SECRET  # Should show your secret

# Ensure the code is installed in your AI's environment
cd claude-ipc-mcp/tools

# Use the scripts directly
python3 ./ipc_register.py gemini
python3 ./ipc_send.py claude "Hey Claude, can you review this?"
python3 ./ipc_check.py

Usage Examples

Asynchronous Messaging

# Monday - User creates Barney
Register this instance as barney
Send to nessa: Welcome to the team! I'm Barney, the troubleshooter.

# Wednesday - User creates Nessa
Register this instance as nessa
Check messages
> "Welcome to the team! I'm Barney, the troubleshooter." (sent 2 days ago)

Gemini CLI as Server

# 8:00 AM - Gemini starts first
[Gemini CLI] Register this instance as gemini
> Registered as gemini (Server started on port 9876)

# 8:05 AM - Claude connects
[Claude Code] Register this instance as claude
> Registered as claude (Connected to existing server)

Live Renaming

# Fred needs to debug
rename to fred-debugging

# Messages to "fred" automatically forward to "fred-debugging" for 2 hours!

Large Message Handling

msg claude: [20KB of debug logs]

# Claude receives:
> "Debug output shows memory leak in... Full content saved to: 
> /ipc-messages/large-messages/20250106-143022_barney_claude_message.md"

Available Commands

The system accepts various natural language commands:

• Register this instance as rose
• check messages or msgs? or any messages?
• msg claude: hello or send to claude: hello
• broadcast: team meeting in 5
• list instances or who's online?
• start auto checking or start auto checking 5
• stop auto checking
• auto check status or is auto checking on?

Troubleshooting

MCP Tools Not Available

• Solution: Restart your Claude Code session completely (exit and start fresh)
• Don't use --continue or --resume flags after MCP changes

Old Installation Conflicts

• Symptoms: Import errors, module not found, UV sync fails
• Solution: Remove old virtual environments with rm -rf venv/ .venv/

Messages Not Persisting

• Check the SQLite database at ~/.claude-ipc-data/messages.db
• Ensure you have write permissions on the directory

"Connection Refused" Errors

• Cause: No server is running
• Solution: The first AI to register will start the server automatically

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "claude-ipc" '{"command":"uvx","args":["--from",".","claude-ipc-mcp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "claude-ipc": {
            "command": "uvx",
            "args": [
                "--from",
                ".",
                "claude-ipc-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "claude-ipc": {
            "command": "uvx",
            "args": [
                "--from",
                ".",
                "claude-ipc-mcp"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect