mcp-talk 0.2.0

Inter-agent messaging via Model Context Protocol

MCP Talk

Inter-agent messaging via Model Context Protocol (MCP).

A lightweight messaging system that enables AI agents (Claude, Codex, Gemini, etc.) to communicate with each other in real-time through a shared message queue.

Features

• Simple tools: send, check, ack, broadcast, list, clean, reply
• File-based persistence: Messages stored as JSON files for easy debugging
• Namespace isolation: Separate message queues per project
• Cross-agent: Works with any MCP-compatible AI assistant
• Zero dependencies: Just Python 3.10+ and the MCP SDK

Installation

# From PyPI (recommended)
pipx install mcp-talk

# Or with pip
pip install mcp-talk

# From source
git clone https://github.com/devinvenable/mcp-talk.git
cd mcp-talk
pipx install .

Configuration

Add to your MCP client configuration:

Claude Desktop / Claude Code

{
  "mcpServers": {
    "mcp-talk": {
      "command": "mcp-talk"
    }
  }
}

Using uvx (no install required)

{
  "mcpServers": {
    "mcp-talk": {
      "command": "uvx",
      "args": ["mcp-talk"]
    }
  }
}

Codex CLI (~/.codex/config.toml)

[mcp_servers.mcp-talk]
command = "mcp-talk"

Gemini CLI (~/.gemini/settings.json)

{
  "mcpServers": {
    "mcp-talk": {
      "command": "mcp-talk"
    }
  }
}

Tools

send - Send a direct message

send(to="codex", message="Please review PR #123", from_agent="claude")

check / chk - Check messages

check(agent="claude")
chk(agent="claude", include_body=true, auto_ack=true)

Returns up to 5 messages by default. Use include_body=true for full message text, auto_ack=true to delete after reading.

broadcast - Send to all agents

broadcast(message="Standup in 5 minutes", from_agent="pm")

ack - Acknowledge/delete a message

ack(id="20251126_143022_abc12345")

reply - Reply to a message

reply(id="20251126_143022_abc12345", message="Done!", from_agent="gemini")

Automatically sends response to original sender and acknowledges the original message.

list - List all messages (PM view)

list(limit=10, include_body=true)

clean - Remove old messages

clean(hours=24)

Namespaces

Isolate messages between projects using the namespace parameter:

# Game project
send(to="gemini", message="Review level 3", namespace="game")
check(agent="gemini", namespace="game")

# Work project
send(to="gemini", message="Review PR #123", namespace="work")
check(agent="gemini", namespace="work")

Messages are stored in separate directories:

~/.mcp_talk/q/           # default (no namespace)
~/.mcp_talk/q/game/      # namespace="game"
~/.mcp_talk/q/work/      # namespace="work"

Message Format

Messages are stored as JSON files in ~/.mcp_talk/q/:

{
  "id": "20251126_143022_abc12345",
  "from": "claude",
  "to": "codex",
  "type": "direct",
  "created": "2025-11-26T14:30:22+00:00",
  "message": "Please review PR #123",
  "namespace": "work"
}

Environment Variables

Variable	Default	Description
MCP_TALK_QUEUE	~/.mcp_talk/q/	Message queue directory
MCP_TALK_AUTO_CLEAN_HOURS	24	Auto-delete messages older than N hours (0 to disable)
MCP_TALK_MAX_MESSAGE_CHARS	2000	Maximum message length

Multi-Agent Setup Tips

Teaching agents to check messages

The chk shortcut is designed to be a simple keyword you can add to agent instructions. Add to your agent's system prompt or memory:

Gemini (~/.gemini/instructions.md):

When I read new messages, I should investigate the topic, verify assertions, and contribute my own expertise to the team.

Claude (CLAUDE.md in project):

When starting work, check for messages with: chk(agent="claude")

Codex (~/.codex/instructions.md):

Before starting tasks, check the message queue for any team communications.

Recommended MCP config with env overrides

Customize behavior per-agent with environment variables:

# ~/.codex/config.toml
[mcp_servers.mcp-talk]
command = "mcp-talk"
env = { MCP_TALK_AUTO_CLEAN_HOURS = "12", MCP_TALK_MAX_MESSAGE_CHARS = "1200" }

// ~/.gemini/settings.json
{
  "mcpServers": {
    "mcp-talk": {
      "command": "mcp-talk",
      "env": {
        "MCP_TALK_AUTO_CLEAN_HOURS": "12",
        "MCP_TALK_MAX_MESSAGE_CHARS": "1200"
      }
    }
  }
}

Example Workflow

1. Claude sends a task to Gemini:

   send(to="gemini", message="Please review the authentication module", from_agent="claude")
   

2. Gemini checks for messages:

   chk(agent="gemini")
   

3. Gemini replies when done:

   reply(id="20251126_143022_abc12345", message="Review complete, LGTM!", from_agent="gemini")
   

4. Claude receives the reply:

   chk(agent="claude")
   

Development

# Clone and install in development mode
git clone https://github.com/devinvenable/mcp-talk.git
cd mcp-talk
pip install -e .

# Reinstall after changes (if using pipx)
pipx install --force .

License

MIT