MCP Agent Mail: a Git-backed inbox for coding agents that share a repo

The problem MCP Agent Mail actually solves

Run several coding agents against one repository and the failure is not intelligence, it is bookkeeping. Two agents edit the same module, one panics on an unexpected diff, and a human ends up relaying context between terminals. The README states the project exists for exactly that situation and lists the symptoms: overwritten edits, missed context from parallel workstreams, and humans acting as liaison between tools.

The intended users are FastMCP clients and CLI tools. The README names Claude Code, Codex, Gemini CLI and Factory Droid as examples, coordinating across one or more codebases. The unit of coordination is a temporary-but-persistent identity such as GreenCastle, which is how an agent gets an address rather than being an anonymous process.

What it is not: a scheduler, a merge tool, or a replacement for Git. It is a communication and intent-signalling layer. The README calls it "asynchronous email + directory + change-intent signaling for your agents", which is a fair summary of the scope.

Identities, Git-backed mailboxes and advisory leases

Two storage layers do different jobs. Git holds the human-auditable artifacts, so messages and leases land as files you can read, diff and review after the fact. SQLite handles indexing and queries, which is what makes search and threading practical rather than a directory scan.

On top of that, the server exposes a set of capabilities through FastMCP: register an identity, send and receive GitHub-Flavored Markdown messages with images, search and thread conversations, declare advisory file reservations on files or globs, and inspect a directory of active agents, programs and models. The README describes the reservation mechanism as "voluntary file reservation leases" and elsewhere as advisory. That word matters. A lease signals intent; it does not stop another agent from writing to the file. Enforcement lives in the agents and in your instructions to them, not in the server.

The server itself is described as HTTP-only FastMCP. Release v0.3.0 added stdio transport, tool filtering and push notifications, so the transport story has since broadened beyond the HTTP-only framing in the README body. Tool filtering is the more interesting of the three: an agent that only sends mail does not need the lease tools in its context window.

Installing it and sending a first message

The README gives a one-line installer. It installs uv and jq if missing, creates a Python 3.14 virtual environment, runs auto-detect integration for supported agent tools, starts the MCP HTTP server on port 8765, prints a masked bearer token, writes helper scripts under scripts/, and adds an am shell alias to your .zshrc or .bashrc.

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yes

The same block documents flags for controlling where things land and whether the server starts: --dir, --project-dir, --no-start, --start-only, --port and --token. After installation, the README says the server can be started from anywhere with the am alias.

am

Two installer side effects deserve attention before you run it. First, it installs Beads Rust (br) and creates a bd alias pointing at br, replacing an existing Beads Go installation. The README is explicit that this replaces any existing bd. Pass --skip-beads to opt out, and --skip-bv to skip the Beads Viewer TUI. Second, the installer creates a run_server_with_token.sh helper under scripts/, which is where the bearer token handling lives.

For a container deployment, the repository ships compose.yaml with the server on port 8765, STORAGE_ROOT set to /data/mailbox and a named volume at /data. The docker-compose.yml file takes a different route, pairing the server with a postgres:16-alpine service and a DATABASE_URL of postgres+asyncpg://agent:agent@db:5432/agent_mail. Those are two distinct deployment shapes in the same repository, and the default credentials in the compose file are placeholders, not something to expose.

If you want to see the client side, the repository includes examples/client_bootstrap.py.

Where the coordination model breaks down

The leases are advisory. An agent that ignores the directory, or one that is not running MCP Agent Mail at all, will write to a reserved file and nothing in the server will stop it. If your problem is genuinely concurrent writes to the same path, you need locking at the filesystem or VCS layer, not a message that says someone intends to edit a file. This is the single largest gap between what the feature name suggests and what it does.

There is a second failure mode in the installer. It replaces the Go Beads CLI with the Rust one by default. The README argues the case: br is the actively maintained version, both use the same .beads/issues.jsonl format, and a bd-br-migration skill is installed for agents to adapt to CLI differences. That is a reasonable migration story, but it is still a default that changes a tool on your machine. Anyone with scripts calling bd should read the beads_rust repository for CLI differences before running the installer without --skip-beads.

Scale is the third boundary. Git-backed artifacts are excellent for auditability and poor for high message volume. Every message and lease is a commit-shaped artifact. The README does not document a retention or compaction policy for the archive, so a long-running swarm writing constantly is a question the documentation leaves open.

Finally, the README's own framing includes a commercial Companion app, an iOS app and host automation for provisioning and steering fleets, with Message Stacks, Human Overseer broadcasts and Double-Arm confirmations for destructive work. The open source server stands on its own, but the pitch for hands-off fleet operation points at a paid product. Read the README with that boundary in mind.

How it compares to a shared task file or a message queue

The closest alternative is not another MCP server, it is a shared file: an AGENTS.md plus a task list that every agent reads and appends to. That approach costs nothing and needs no server, but it has no identity model, no per-agent inbox, no search, and no way to ask which agents are currently active. MCP Agent Mail exists because that file becomes a write-contention point and a context-window tax once more than two agents touch it.

The other alternative is a general message broker such as Redis, which appears in the dependency list as redis[hiredis]. A broker gives you pub/sub and queues with far better throughput. What it does not give you is a human-readable archive of what agents said to each other, or a directory of who is working on what. The Git layer is the differentiator, and it is also the reason this project will never match a broker on volume.

Against a plain Git branching discipline, the difference is timing. Branches separate work after the fact; leases and messages signal intent before the edit happens. That is the whole value proposition, and it depends entirely on agents choosing to participate.

Maintenance, upgrades and the licence mismatch

The last push to the default branch was on 2026-09-06, and the repository is not archived. Releases are sparse: v0.3.2 on 2026-04-16, v0.3.0 on 2026-01-07 and v0.2.1 on 2026-01-06. pyproject.toml declares version 0.3.4, so the package version runs ahead of the tagged releases. The classifiers mark Development Status as 3 - Alpha, and the README's own status line says the project is under active development with the design captured in docs/planning/project_idea_and_guide.md.

Upgrade cost is dominated by the installer rather than the Python package. Because install.sh wires up agent tool integrations, writes helper scripts and edits your shell rc file, re-running it is not a neutral operation. The --skip-beads and --skip-bv flags exist precisely so you can re-run it without re-installing adjacent tooling. The container path is cleaner for upgrades: rebuild the image and keep the volume.

The licence needs a decision from someone other than a reviewer. pyproject.toml declares MIT and includes the OSI classifier, but the repository's licence metadata is NOASSERTION, meaning GitHub could not match the LICENSE file to a known licence. Those two facts are inconsistent, and the LICENSE file at the repository root is the document that governs. This is not legal advice; it is a pointer to the file worth reading before you depend on the project.

Editorial conclusion

Adopt MCP Agent Mail if you already run two or more coding agents against one repository and you want their intent, messages and file claims recorded in files you can read and diff. Skip it if you run a single agent, if you need hard write locking rather than advisory leases, or if you cannot accept that the installer replaces an existing Beads Go CLI with the Rust one unless you pass --skip-beads. Before wiring it into a real repo, verify three things: that port 8765 is free on the host, that the bearer token printed at install is stored somewhere your agents can read, and that the STORAGE_ROOT path you choose survives container restarts. The licence metadata is the open question: pyproject.toml declares MIT, but the repository is classified NOASSERTION, and that mismatch is worth resolving before this becomes infrastructure.

Frequently asked questions

Official sources

1. Dicklesworthstone/mcp_agent_mail on GitHub
2. Issues
3. README
4. Releases