a2a-mailbox
File-based messaging that lets terminal coding agents send each other mail
- Pricing
- Open source
- Platforms
- Linux, Windows, CLI
- Runs
- Locally
- Version
- 0.2.0
- Listing updated
- today
Similar MCP servers
About a2a-mailbox
a2a-mailbox is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.
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.
Install
Run in a terminal
claude mcp add a2a-mailbox -- npx -y https://github.com/RegretSSS/a2a-mailbox/releases/download/v0.2.0/a2a-mailbox.mcpbAdd to claude_desktop_config.json
{
"mcpServers": {
"a2a-mailbox": {
"command": "npx",
"args": [
"-y",
"https://github.com/RegretSSS/a2a-mailbox/releases/download/v0.2.0/a2a-mailbox.mcpb"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"a2a-mailbox": {
"command": "npx",
"args": [
"-y",
"https://github.com/RegretSSS/a2a-mailbox/releases/download/v0.2.0/a2a-mailbox.mcpb"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"a2a-mailbox": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"https://github.com/RegretSSS/a2a-mailbox/releases/download/v0.2.0/a2a-mailbox.mcpb"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"a2a-mailbox": {
"command": "npx",
"args": [
"-y",
"https://github.com/RegretSSS/a2a-mailbox/releases/download/v0.2.0/a2a-mailbox.mcpb"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"a2a-mailbox": {
"command": "npx",
"args": [
"-y",
"https://github.com/RegretSSS/a2a-mailbox/releases/download/v0.2.0/a2a-mailbox.mcpb"
]
}
}
}Using several servers? Build one config file with the MCP config generator.
Tools this server provides (6)
Taken from the project documentation; the running server may differ.
- 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
What it does
- 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
Pricing
Open source
Apache-2.0
a2a-mailbox 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.


