MCP Agent Mail

MCP Agent Mail is an open-source coordination server for multi-agent coding workflows, built by Jeffrey Emanuel (GitHub: Dicklesworthstone). It exposes an HTTP-only FastMCP server that gives coding agents memorable identities, an inbox/outbox, searchable message history, and advisory file reservation "leases" to prevent agents from stepping on each other's edits. The project describes itself as "like Gmail for your coding agents" and is under active development, with its latest release at v0.3.2.

What It Is

MCP Agent Mail is a lightweight, asynchronous coordination fabric for teams of AI coding agents running in parallel on the same codebase or across related repositories. Rather than requiring humans to relay messages between agent tools, it provides a shared communication bus backed by Git (for human-auditable artifacts) and SQLite with FTS5 (for fast indexing and queries). Agents register temporary-but-persistent identities (e.g., "GreenCastle"), send and receive GitHub-Flavored Markdown messages with optional image attachments, and declare advisory file reservations to signal editing intent before touching shared files.

Architecture and Persistence Model

The server uses a dual persistence model:

• Git-backed markdown: Every canonical message, inbox/outbox copy, and file reservation JSON is committed to a per-project Git repository, making all agent communication fully auditable by humans.
• SQLite with FTS5: A relational database indexes messages, agents, threads, and file reservations for fast search and directory queries. An external-content FTS virtual table with triggers keeps the search index current on every insert, update, or delete.

The on-disk layout organizes artifacts under <store>/projects/<slug>/ with subdirectories for agents, messages (by year/month), file reservations (content-addressed by SHA-1), and attachments (WebP, content-addressed). Concurrency is managed with per-project .archive.lock and repo-level .commit.lock files.

Core Capabilities

• Agent identities: Memorable adjective+noun names, unique per project; profiles persisted to Git.
• Inbox/outbox messaging: Send/receive GFM messages with images; thread support via shared thread_id; importance levels and acknowledgment tracking.
• Advisory file reservations (leases): TTL-based exclusive or shared leases on file paths/globs; optional pre-commit and pre-push Git hooks block commits that conflict with another agent's active exclusive reservation.
• Full-text search: FTS5-powered search over subject and body with field filters, phrase search, and boolean operators; automatic LIKE fallback.
• Contact model: Per-agent policies (open, auto, contacts_only, block_all) with auto-allow heuristics for same-thread participants and overlapping file reservations.
• Web UI: A server-rendered human-facing mail viewer at /mail with project browsing, agent inboxes, message detail, search, file reservations, and a Human Overseer composer for sending high-priority messages to agents.
• Static mailbox export: Export project mailboxes to portable, read-only static bundles deployable to GitHub Pages, Cloudflare Pages, S3, or Nginx; supports Ed25519 signing, age encryption, and FTS5-backed search in the viewer.
• Disaster recovery: archive save/restore commands create restorable ZIP snapshots of the SQLite database and Git storage repo.
• Mailbox health diagnostics: am doctor checks for stale locks, orphaned records, FTS desync, and expired reservations, with semi-automatic repair and backup creation.

Integrations and Tooling

MCP Agent Mail is designed for FastMCP clients and CLI-based coding agents including Claude Code, OpenAI Codex CLI, Gemini CLI, and Factory Droid. The installer auto-detects installed agent tools and wires up the MCP server configuration. It also installs:

• Beads Rust (br): A Rust reimplementation of the Beads task tracker for dependency-aware task planning, aliased as bd for backwards compatibility.
• Beads Viewer (bv): A terminal UI providing graph analytics (PageRank, critical path, cycle detection) via robot flags designed for AI agent consumption.

The server supports Docker and Docker Compose deployment, running as an unprivileged user with a health check endpoint.

Update: v0.3.2

The latest release is v0.3.2, published on April 16, 2026. The repository was last pushed on June 27, 2026, and last updated on July 1, 2026, indicating active ongoing development. The project was created on October 23, 2025, and has accumulated over 2,000 GitHub stars and 211 forks according to the repository metadata. Recent development has added the interactive deployment wizard with session resumption, Cloudflare Pages support, virtual scrolling for the static viewer, OPFS caching, the share update command for refreshing existing bundles, and the am doctor diagnostics suite.