Content
# 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
```bash
# 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
```json
{
"mcpServers": {
"mcp-talk": {
"command": "mcp-talk"
}
}
}
```
### Using uvx (no install required)
```json
{
"mcpServers": {
"mcp-talk": {
"command": "uvx",
"args": ["mcp-talk"]
}
}
}
```
### Codex CLI (~/.codex/config.toml)
```toml
[mcp_servers.mcp-talk]
command = "mcp-talk"
```
### Gemini CLI (~/.gemini/settings.json)
```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/`:
```json
{
"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:
```toml
# ~/.codex/config.toml
[mcp_servers.mcp-talk]
command = "mcp-talk"
env = { MCP_TALK_AUTO_CLEAN_HOURS = "12", MCP_TALK_MAX_MESSAGE_CHARS = "1200" }
```
```json
// ~/.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
```bash
# 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
