MCP Agent Mail - Mail-like coordination layer for multi-agent workflows. Identities, inbox/outbox, file reservations, contact policies, threaded messaging, pre-commit guard, Human Overseer, static exports, disaster recovery. Git+SQLite backed. Python/FastMCP.
A mail-like coordination layer for coding agents exposed as an HTTP-only FastMCP server. Provides memorable identities, inbox/outbox, file reservation leases, contact policies, searchable message history, and Human Overseer messaging. Backed by Git (human-auditable artifacts) and SQLite (fast queries with FTS5).
Without coordination, multiple agents:
Agent Mail solves this with:
# Quickest way (alias added during install)
am
# Or manually
cd ~/projects/mcp_agent_mail
./scripts/run_server_with_token.sh
Default: http://127.0.0.1:8765
Web UI for humans: http://127.0.0.1:8765/mail
Each working directory (absolute path) is a project. Agents in the same directory share a project namespace. Use the same project_key for agents that need to coordinate.
Agents register with adjective+noun names (GreenCastle, BlueLake). Names are unique per project, memorable, and appear in inboxes, commit logs, and the web UI.
Advisory locks on file paths or globs. Before editing files, reserve them to signal intent. Other agents see the reservation and can choose different work. The optional pre-commit guard blocks commits that conflict with others' exclusive reservations.
Per-agent policies control who can message whom:
| Policy | Behavior |
|---|---|
open | Accept any message in the project |
auto (default) | Allow if shared context exists (same thread, overlapping reservations, recent contact) |
contacts_only | Require explicit contact approval first |
block_all | Reject all new contacts |
GitHub-Flavored Markdown with threading, importance levels (low, normal, high, urgent), and optional acknowledgment requirements. Images are auto-converted to WebP.
macro_start_session(
human_key="/abs/path/to/project",
program="claude-code",
model="opus-4.5",
task_description="Implementing auth module"
)
Returns: {project, agent, file_reservations, inbox}
This single call: ensures project exists, registers your identity, optionally reserves files, fetches your inbox.
file_reservation_paths(
project_key="/abs/path/to/project",
agent_name="GreenCastle",
paths=["src/auth/**/*.ts", "src/middleware/auth.ts"],
ttl_seconds=3600,
exclusive=true,
reason="bd-123"
)
Returns: {granted: [...], conflicts: [...]}
Conflicts are reported but reservations are still granted. Check conflicts and coordinate if needed.
send_message(
project_key="/abs/path/to/project",
sender_name="GreenCastle",
to=["BlueLake"],
subject="[bd-123] Starting auth refactor",
body_md="Reserving src/auth/**. Will update session handling.",
thread_id="bd-123",
importance="normal",
ack_required=true
)
fetch_inbox(
project_key="/abs/path/to/project",
agent_name="GreenCastle",
limit=20,
urgent_only=false,
include_bodies=true
)
Or use resources for fast reads: