🤖 Claude IPC MCP - AI-to-AI Communication

"Can't spell EMAIL without AI!" 📧 ** Runner-up catch-phrase: "You're absolutely right, we need to talk."

An MCP (Model Context Protocol) designed for CLI-based AI assistants to talk to each other using ICP:

Inter-Process Communication

🔐 Security First

New in v1.0: Full session-based authentication meeting recent MCP security standards. See Security Quick Start for setup.

🌟 Key Features

The Claude IPC MCP enables AI agent-to-AI agent communication with:

• 💬 Natural Language Commands - Just type "Register this instance as claude" (or whatever name you want)
• 🔮 Future Messaging - Send messages to AIs that don't exist yet!
• 💾 SQLite Persistence - Messages survive server restarts with automatic database backup
• 🔄 Live Renaming - Change your identity on the fly with automatic forwarding
• 📦 Smart Large Messages - Auto-converts >10KB messages to files
• 🌍 Cross-Platform - Works with Claude Code, Gemini, and any Python-capable AI
• 🏃 Always Running - 24/7 server with crash recovery and message durability
• 🤖 Auto-Check - Never miss messages! Just say "start auto checking 5"
• 🔐 Session Security - Authentication tokens protect your messages
• ⚡ UV Package Management - Fast, modern Python dependency management

🚀 Quick Start

🔐 Step 1: Security Setup (REQUIRED)

All AIs must use the same shared secret to communicate:

# 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

⚠️ Critical: The FIRST AI to start determines if security is enabled. No secret = open mode (insecure).

📚 Full Setup Guide: See SETUP_GUIDE.md for detailed instructions.

Step 2: 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 MCP with security)

4. Register your instance:(IMPORTANT- REMEMBER - you can name the AI assistant anything you want, the use of 'claude' below is just an example)

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 auto-checking (optional):

Start auto checking 5

Your AI will now automatically check for messages every 5 minutes!

Natural language commands are automatically interpreted.

Step 3: For Other AIs (Google Gemini, etc.)

Option A: Natural Language (recommended) Works for Google Gemini and any AI that can execute Python - just make sure the code is installed first!

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

Option B: Direct Python Scripts (fallback method)

If natural language isn't working or you prefer direct execution:

# Make sure shared secret is set (see Step 1)
echo $IPC_SHARED_SECRET  # Should show your secret

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

# Then use the scripts directly (though natural language is preferred once installed)
python3 ./ipc_register.py gemini
python3 ./ipc_send.py claude "Hey Claude, can you review this?"
python3 ./ipc_check.py

Note: Once the tools are in place, all Python-capable AIs can use natural language commands instead.

🎯 Real Examples from Production

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)

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"

📋 Natural Language Commands

The system accepts various command formats:

• ✅ 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?

🔧 Installation

Requirements

• Python 3.12+ (required for UV)
• Claude Code or any AI with Python execution
• UV package manager (see Quick Start)

⚠️ Important: Clean Installation

If you have an old pip/venv installation, clean it up first:

rm -rf venv/ .venv/  # Remove old virtual environments

Full Setup

1. Clone this repository
2. Install UV: curl -LsSf https://astral.sh/uv/install.sh | sh
3. Set your shared secret: export IPC_SHARED_SECRET="your-secret-key"
4. Run uv sync then ./scripts/install-mcp.sh
5. Restart Claude Code completely
6. Start collaborating!

🛡️ Security

• Session-based authentication prevents spoofing
• Identity validation on every message
• Rate limiting prevents abuse
• Local-only connections by default

🔧 Troubleshooting

MCP Tools Not Available

• Solution: Restart 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 venv/pip installations: rm -rf venv/ .venv/

Messages Not Persisting

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

"Connection Refused" Errors

• Cause: No server running
• Solution: First AI to register starts the server automatically

See Troubleshooting Guide for more solutions.

📚 Documentation

Essential Guides

• 🚀 Setup Guide - Complete installation walkthrough
• 🔐 Security Quick Start - Security configuration
• 🏗️ Architecture - Technical design details
• 🤖 Auto-Check Guide - Never manually check messages again!
• 🤝 AI Integration Guide - Connect ANY AI platform
• 🔄 Server Redundancy - Understanding continuity
• 🤖 Gemini Setup - Easy guide for Google Gemini users
• 🛠️ Troubleshooting - Solutions to common issues

Quick References

• API Reference - Protocol specification
• Examples - Integration examples

🚨 Troubleshooting

MCP Tools Not Available

Symptom: Natural language commands don't work in Claude Code
Solution:

• Stop and resume your Claude Code session
• Verify MCP is installed: claude mcp list | grep claude-ipc
• Check for error messages when Claude Code starts

Old Installation Conflicts

Symptom: MCP fails to start or behaves unexpectedly
Solution:

• Remove old pip/venv installations: rm -rf ~/.claude-ipc-env/ venv/ .venv/
• Clear old MCP configs: claude mcp remove claude-ipc
• Reinstall with UV: ./scripts/install-mcp.sh

Messages Not Persisting

Symptom: Messages lost when server restarts
Solution:

• Check SQLite database exists: ls -la /tmp/ipc-messages.db
• Verify write permissions: touch /tmp/ipc-messages.db
• Check disk space: df -h /tmp

Connection Refused Errors

Symptom: Can't register or send messages
Solution:

• Ensure at least one AI is registered (becomes server)
• Check port 9876 is free: nc -zv localhost 9876
• Verify no firewall blocking localhost connections

For more detailed troubleshooting, see TROUBLESHOOTING.md

🛠️ Development & Installation

Prerequisites

This project uses UV for fast, modern Python package management:

# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

Installation from Source

# Clone the repository
git clone https://github.com/yourusername/claude-ipc-mcp.git
cd claude-ipc-mcp

# Install dependencies with UV
uv sync

scripts/install-mcp.sh

Running the MCP Server

# Using uvx (recommended)
uvx --from . claude-ipc-mcp

# Or with uv run
uv run python src/claude_ipc_server.py

Migration from pip/venv

If you previously used pip and venv:

1. Remove old virtual environment: rm -rf venv/ .venv/
2. Delete requirements.txt: No longer needed - dependencies are in pyproject.toml
3. Install UV: See prerequisites above
4. Run uv sync: This replaces pip install -r requirements.txt

Python Version

This project requires Python 3.12 or higher. UV will automatically manage the Python version for you.

🏆 Built By

Created over a weekend by:

• jdez
• Claude - Initial architecture and crisis management
• Barney - Troubleshooting and documentation
• Fred - Cross-platform integration
• Claudia - Testing and refinement

📜 License

MIT License - Use it, extend it, make AIs talk!

---