# 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