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
-
Claude sends a task to Gemini:
send(to="gemini", message="Please review the authentication module", from_agent="claude") -
Gemini checks for messages:
chk(agent="gemini") -
Gemini replies when done:
reply(id="20251126_143022_abc12345", message="Review complete, LGTM!", from_agent="gemini") -
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