# a2a-mailbox

> a2a-mailbox is an open-source MCP server for developer tools. File-based messaging that lets terminal coding agents send each other mail. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** Linux, Windows, CLI, self-hosted
- **Repository:** https://github.com/regretsss/a2a-mailbox
- **MCP Registry name:** io.github.RegretSSS/a2a-mailbox
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools), [AI models and LLM tooling](https://ai-powered.com/categories/ai-and-llm)
- **Listing updated:** 2026-11-18

## About

The project name echoes Google's Agent2Agent protocol, but the author states the two are unrelated: this is a file mailbox between terminal agents, not a protocol implementation. Agents such as Claude Code, Codex, Pi, ZCode and DSH send and read messages like email, backed by a file queue and a resident hub daemon.

The hub picks a delivery channel based on the recipient: tmux injection for Claude Code, a native inbox queue for Pi, a daemon queue for Codex, pull-based polling for ZCode and an RPC queue for DSH. Delivery follows a doorbell model in which queuing counts as delivered, injection is a best-effort nudge and an explicit acknowledgement means read. Messages can also cross machines through SSH federation.

Six tools are exposed over stdio, with an optional HTTP gateway. Access is controlled by scope locks for subagents and group admission lists. The README says the protocol has no built-in authentication and should not be exposed to untrusted networks. It needs Python 3.11+, fastmcp and tmux, and is licensed Apache-2.0.

## Features

- **Five delivery channels:** tmux injection, native queue, daemon queue, RPC queue or pull, chosen per recipient.
- **Cross-host federation:** Hubs exchange registries and deliver messages over SSH.
- **Acknowledgement model:** Queued means delivered; an ack means read.
- **Group admission:** Gate lists decide which agents may message you.
- **Subagent scope lock:** Limit a derived agent to talking to its parent.
- **Optional HTTP gateway:** A resident gateway avoids stdio pipe chains on Windows.

## Good for

- Let a Claude Code session hand a task to a Codex session
- Notify an agent that mail is waiting while it runs a long job
- Coordinate agents running on two machines over SSH
- Restrict a subagent so it cannot message arbitrary agents
- Audit message history from local files

## Install

### Claude Code (Terminal)

```sh
claude mcp add a2a-mailbox -- npx -y https://github.com/RegretSSS/a2a-mailbox/releases/download/v0.2.0/a2a-mailbox.mcpb
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "a2a-mailbox": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/RegretSSS/a2a-mailbox/releases/download/v0.2.0/a2a-mailbox.mcpb"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "a2a-mailbox": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/RegretSSS/a2a-mailbox/releases/download/v0.2.0/a2a-mailbox.mcpb"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "a2a-mailbox": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/RegretSSS/a2a-mailbox/releases/download/v0.2.0/a2a-mailbox.mcpb"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "a2a-mailbox": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/RegretSSS/a2a-mailbox/releases/download/v0.2.0/a2a-mailbox.mcpb"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "a2a-mailbox": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/RegretSSS/a2a-mailbox/releases/download/v0.2.0/a2a-mailbox.mcpb"
      ]
    }
  }
}
```

## Tools

- `mail_send`: Send a message, optionally as a reply and optionally expecting a reply
- `mail_poll`: List own pending message summaries without consuming them
- `mail_read`: Read a full message including its ack id
- `mail_ack`: Confirm a message as read
- `mail_who`: List registered agents and federated peers
- `mail_group`: Manage group admission: join, pending, admit, revoke and gate

## FAQ

### Is it the Google A2A protocol?

No. The author says the name is shared but the project is unrelated; it is a file mailbox for terminal agents.

### What does it need?

Python 3.11+, the fastmcp package and tmux; Pi needs an extension file.

### Does it work on Windows?

A pure Windows node is described as experimental and verified on a single machine.

### Is there authentication?

No built-in authentication; trust is limited to the local user and passwordless SSH peers.

### What licence?

Apache-2.0.

### Is a2a-mailbox free?

Yes. a2a-mailbox is open source, so you can use and self-host it for free.

### How do I add a2a-mailbox to Claude Code?

Run this command in your terminal: claude mcp add a2a-mailbox -- npx -y https://github.com/RegretSSS/a2a-mailbox/releases/download/v0.2.0/a2a-mailbox.mcpb

### What are the best alternatives to a2a-mailbox?

The closest alternatives to a2a-mailbox are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/a2a-mailbox
