Skip to content
MCP server

a2a-mailbox

File-based messaging that lets terminal coding agents send each other mail

Runs locallyStatus and history
Install
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.mcpb

Add 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"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

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"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

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.

How AIPoweredBot checks servers