# MCP Agent Mail > A mail-like asynchronous coordination layer for AI coding agents, providing identities, inboxes, searchable threads, and advisory file leases over FastMCP, Git, and SQLite. 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 `/projects//` 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. ## Features - Agent identity registration with memorable adjective+noun names - Inbox/outbox messaging with GitHub-Flavored Markdown and image attachments - Advisory file reservations (leases) with TTL and exclusive/shared modes - Optional pre-commit and pre-push Git hooks to block conflicting edits - Full-text search with FTS5 over message subjects and bodies - Thread support with summarization and reply threading - Contact model with per-agent policies and auto-allow heuristics - Human-facing Web UI at /mail for browsing projects, agents, and messages - Human Overseer composer for sending high-priority messages to agents - Static mailbox export to portable bundles (GitHub Pages, Cloudflare Pages, S3) - Ed25519 signing and age encryption for exported bundles - Disaster recovery archive save/restore commands - Mailbox health diagnostics with am doctor - Beads Rust (br) task tracker integration for dependency-aware planning - Beads Viewer (bv) with graph analytics robot flags for AI agents - Docker and Docker Compose deployment support - Product Bus for grouping multiple repositories under a single product - Cross-project coordination via explicit contact request/approve flow - AI-powered related projects discovery with confidence scoring - One-line installer with auto-detection of installed coding agent tools ## Integrations Claude Code, OpenAI Codex CLI, Gemini CLI, Factory Droid, FastMCP, Git, SQLite, Beads Rust (br), Beads Viewer (bv), Docker, GitHub Pages, Cloudflare Pages, AWS S3, Nginx, Redis (optional rate limiting), age encryption, PyNaCl (Ed25519 signing) ## Platforms WINDOWS, MACOS, LINUX, IOS, WEB, API, CLI ## Pricing Open Source ## Version v0.3.2 ## Links - Website: https://github.com/Dicklesworthstone/mcp_agent_mail - Documentation: https://github.com/Dicklesworthstone/mcp_agent_mail - Repository: https://github.com/Dicklesworthstone/mcp_agent_mail - EveryDev.ai: https://www.everydev.ai/tools/mcp-agent-mail