MCP Agent Mail (Rust)
A mail server for agents sharing one repository: messages, threads, file reservations and a 16-screen TUI
- 234 ★ on the repository
- Last commit
Extended access
Why this level
- The installer downloads a binary and edits the configuration of detected agents itself, Codex CLI included
- The server listens on the local port `127.0.0.1:8765`, and messages and agent profiles are written as files in project Git repositories
- The pre-commit hook can block a commit when another agent holds the file
Install
- Works in
Manual install
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail_rust/main/install.sh?$(date +%s)" | bashLinux and macOS. Downloads a binary for the platform, verifies the signature through `minisign` and configures detected agents.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The installer downloads a binary and edits the configuration of detected agents itself, Codex CLI included
- The server listens on the local port `127.0.0.1:8765`, and messages and agent profiles are written as files in project Git repositories
- The pre-commit hook can block a commit when another agent holds the file
This is third-party code. Review the repository files before installing.
What it does
MCP Agent Mail is a local mail server for several agents working on one repository. Each agent gets a persistent name such as `GreenCastle`, an inbox and outbox, threaded conversations and file reservations. Messages are written to the project Git archive and indexed in SQLite, so both humans and search can read them, and they do not occupy the agent context. The server exposes 45 MCP tools and 25 resources. An agent registers the project and itself, reserves globs such as `src/**` for a term, exclusive or shared, sends messages that ask for acknowledgment and reads its inbox. A pre-commit hook blocks commits that touch files reserved by another agent. An operator watches the work in a 16-screen TUI, a web UI at `/mail/` and the `am robot` command with `toon` or `json` output. It is the Rust rewrite of the Python mcp_agent_mail project.
Who it is for. People who run several agents (Claude Code, Codex, Gemini CLI) on one repository and untangle edits that the agents overwrite for each other.
Good fit when
- Different agents own the backend, frontend and scripts, and they have to agree on who edits which files
- An agent crashed or lost its context, but its conversation with the others has to survive: it lives in the Git archive
- You want to see what the agents agreed on in a TUI or a browser, without a retelling in chat
- Beads tasks are tied to conversation threads through `thread_id`, so the discussion stays next to the task
Not a fit when
- There is a single agent: file reservations and mail add overhead for nothing
- Agents run on different machines without a shared filesystem: the server is built for one machine
- You need a single sign-on service for several servers: JWT is supported, but each server manages its own tokens
Example request
Register in Agent Mail, reserve `src/auth/**` for an hour and message BlueLake that you are starting the auth refactorMCP
- Transport
- stdio, http
- Authentication
- not required
Environment variables
AM_SEARCH_SEMANTIC_ENABLED- Turns on semantic and hybrid search in builds with the hybrid feature. Without it every query runs lexical search.
Limitations
File reservations are advisory: an agent bypasses the hook with `git commit --no-verify`. A source build needs Rust nightly. In a swarm of 60 agents the `file_reservation_paths` and `release_file_reservations` calls took 4.7 s at the median and about 15 s at p99 in version 0.3.39, against a 5 s target. The license is MIT with a rider: no rights are granted to OpenAI, Anthropic, their affiliates or anyone acting on their behalf. The terms are in the `LICENSE` file, and people at those companies should read them before use.
How to disable. Stop the server, remove the `agent-mail` entry from `.mcp.json` or the agent configuration and delete the pre-commit hook in the repository. The `install.sh` script with the `--uninstall` flag removes everything.
FAQ
How do I connect Agent Mail to Claude Code?
The installer configures detected agents itself, and `am setup run` repeats that setup. By hand, add an `agent-mail` server to `.mcp.json` with the command `mcp-agent-mail` or, for a running server, the address `http://127.0.0.1:8765/mcp/`.
Do I need a separate server per project?
No, one server handles several projects. A project is identified by the absolute path to the repository, passed as `project_key`.
Can agents in different repositories talk to each other?
Yes. Either both repositories share one `project_key`, or the projects stay separate, are linked with `macro_contact_handshake` and the recipient is addressed as `Name@project`.
What if the server crashes?
Live state sits in SQLite, and the Git archive is the recovery ledger. After database corruption `am doctor reconstruct` rebuilds SQLite from the archive.
Does Agent Mail work with a Claude Max subscription?
Yes. Each agent session connects to the same MCP server regardless of the subscription tier.
Discussion
No questions or reviews yet.
Related
MCP serversMCP Agent Mail
mcp_agent_mail
A mail coordination layer for coding agents: agents have memorable names, inboxes and outboxes, history search and voluntary file reservations
A Rust manager that brings MCP services under one daemon: a CLI, a web UI, an HTTP API and SDKs for Python and Rust
A universal MCP CLI client from Apify: persistent sessions, OAuth, JSON output for scripts and shell access to any MCP server for agents
An MCP server that inserts a human feedback step into agent tasks: a web or desktop window for text, images and prompts
UseAgent’s MCP server sends tasks to remote agents, collects their results and records the runs in an organization’s ledger.
An MCP server and CLI coordinate specialized agents, retain working patterns and connect tasks with project hooks.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| MCP Agent Mail (Rust) (this card) | no | not required | 234 | |
| MCP Agent Mail | no | API key | 2,232 | The Python original with the same mail and reservation model; the Rust version adds a 16-screen TUI, the `am robot` command, Search V3, build slots and a bus across projects. |
| Beads | no | 28,540 | Beads tracks tasks and dependencies, while Agent Mail carries the conversations between agents; per the documentation the task ID serves as the `thread_id` that joins them. |
README in short
The README covers installation with release signature verification, setup for Claude Code, Codex CLI and Gemini CLI, all 45 tools, server modes, the TUI and robot mode. Separate sections cover the reservation algorithms, the consistency model, search and benchmarks against the Python version.