// 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.
| name | agent-mail |
| description | 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="br-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="[br-123] Starting auth refactor",
body_md="Reserving src/auth/**. Will update session handling.",
thread_id="br-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:
resource://inbox/GreenCastle?project=/abs/path&limit=20&include_bodies=true
release_file_reservations(
project_key="/abs/path/to/project",
agent_name="GreenCastle"
)
Prefer macros for speed and smaller models. Use granular tools when you need fine control.
| Macro | Purpose |
|---|---|
macro_start_session | Bootstrap: ensure project → register agent → optional file reservations → fetch inbox |
macro_prepare_thread | Join existing conversation: register → summarize thread → fetch inbox context |
macro_file_reservation_cycle | Reserve files, do work, optionally auto-release when done |
macro_contact_handshake | Request contact permission, optionally auto-accept, send welcome message |
When using Beads for task management, keep identifiers aligned:
1. Pick ready work: br ready --json → choose br-123
2. Reserve files: file_reservation_paths(..., reason="br-123")
3. Announce start: send_message(..., thread_id="br-123", subject="[br-123] Starting...")
4. Work and update: Reply in thread with progress
5. Complete: br close br-123
release_file_reservations(...)
send_message(..., subject="[br-123] Completed")
Use br-### as:
thread_id[br-###]reasonUse bv's robot flags for intelligent task selection:
| Flag | Output | Use Case |
|---|---|---|
bv --robot-insights | PageRank, critical path, cycles | "What's most impactful?" |
bv --robot-plan | Parallel tracks, unblocks | "What can run in parallel?" |
bv --robot-priority | Recommendations with confidence | "What should I work on next?" |
bv --robot-diff --diff-since <ref> | Changes since commit/date | "What changed?" |
Rule of thumb: Use br for task operations, use bv for task intelligence.
For frontend/backend or multi-repo projects:
Option A: Shared project_key
Both repos use the same project_key. Agents coordinate automatically.
Option B: Separate projects with contact links
# Backend agent requests contact with frontend agent
request_contact(
project_key="/abs/path/backend",
from_agent="GreenCastle",
to_agent="BlueLake",
to_project="/abs/path/frontend",
reason="API contract coordination"
)
# Frontend agent accepts
respond_contact(
project_key="/abs/path/frontend",
to_agent="BlueLake",
from_agent="GreenCastle",
accept=true
)
Install the guard to block commits that conflict with others' exclusive reservations:
install_precommit_guard(
project_key="/abs/path/to/project",
code_repo_path="/abs/path/to/project"
)
hooks.d/Set AGENT_NAME environment variable so the guard knows who you are.
Bypass in emergencies: AGENT_MAIL_BYPASS=1 git commit ...
| Tool | Purpose |
|---|---|
ensure_project(human_key) | Create/ensure project exists |
register_agent(project_key, program, model, name?, task_description?) | Register identity |
whois(project_key, agent_name) | Get agent profile with recent commits |
create_agent_identity(project_key, program, model) | Always create new unique agent |
| Tool | Purpose |
|---|---|
send_message(project_key, sender, to, subject, body_md, ...) | Send message |
reply_message(project_key, message_id, sender, body_md) | Reply (preserves thread) |
fetch_inbox(project_key, agent, limit?, since_ts?, urgent_only?) | Get messages |
mark_message_read(project_key, agent, message_id) | Mark as read |
acknowledge_message(project_key, agent, message_id) | Acknowledge receipt |
search_messages(project_key, query) | FTS5 search |
summarize_thread(project_key, thread_id) | Extract key points and actions |
| Tool | Purpose |
|---|---|
file_reservation_paths(project_key, agent, paths, ttl?, exclusive?) | Reserve files |
release_file_reservations(project_key, agent, paths?) | Release reservations |
renew_file_reservations(project_key, agent, extend_seconds?) | Extend TTL |
force_release_file_reservation(project_key, agent, reservation_id) | Clear stale reservation |
| Tool | Purpose |
|---|---|
request_contact(project_key, from_agent, to_agent, reason?) | Request permission to message |
respond_contact(project_key, to_agent, from_agent, accept) | Accept/deny contact request |
list_contacts(project_key, agent_name) | List contact links |
set_contact_policy(project_key, agent_name, policy) | Set open/auto/contacts_only/block_all |
Use resources for quick, non-mutating reads:
resource://inbox/{agent}?project=<path>&limit=20&include_bodies=true
resource://thread/{thread_id}?project=<path>&include_bodies=true
resource://message/{id}?project=<path>
resource://file_reservations/{slug}?active_only=true
resource://project/{slug}
resource://projects
resource://agents/{project_key}
"exact phrase"
prefix*
term1 AND term2
term1 OR term2
subject:login
body:"api key"
(auth OR login) AND NOT admin
Example: search_messages(project_key, '"auth module" AND error NOT legacy')
Browse at http://127.0.0.1:8765/mail:
Send direct messages to agents with automatic preamble:
high importanceExport projects to portable, read-only bundles for auditors, stakeholders, or archives:
# Interactive wizard (recommended)
uv run python -m mcp_agent_mail.cli share wizard
# Manual export
uv run python -m mcp_agent_mail.cli share export --output ./bundle
# With signing
uv run python -m mcp_agent_mail.cli share export \
--output ./bundle \
--signing-key ./keys/signing.key
# Preview locally
uv run python -m mcp_agent_mail.cli share preview ./bundle
standard (removes secrets) or strict (redacts bodies)# Save current state
uv run python -m mcp_agent_mail.cli archive save --label nightly
# List restore points
uv run python -m mcp_agent_mail.cli archive list --json
# Restore after disaster
uv run python -m mcp_agent_mail.cli archive restore <file>.zip --force
# Run diagnostics
uv run python -m mcp_agent_mail.cli doctor check
# Preview repairs
uv run python -m mcp_agent_mail.cli doctor repair --dry-run
# Apply repairs (creates backup first)
uv run python -m mcp_agent_mail.cli doctor repair
Checks: stale locks, database integrity, orphaned records, FTS sync, expired reservations.
| Error | Fix |
|---|---|
| "sender_name not registered" | Call register_agent or macro_start_session first |
| "FILE_RESERVATION_CONFLICT" | Wait for expiry, coordinate, or use non-exclusive |
| "CONTACT_BLOCKED" | Use request_contact and wait for approval |
| Empty inbox | Check since_ts, urgent_only, verify agent name matches exactly |
# One-liner (recommended)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yes
# Custom port
curl -fsSL ... | bash -s -- --port 9000 --yes
# Change port after installation
uv run python -m mcp_agent_mail.cli config set-port 9000
| Variable | Default | Description |
|---|---|---|
STORAGE_ROOT | ~/.mcp_agent_mail_git_mailbox_repo | Root for repos and SQLite DB |
HTTP_PORT | 8765 | Server port |
HTTP_BEARER_TOKEN | — | Static bearer token for auth |
LLM_ENABLED | true | Enable LLM for summaries/discovery |
CONTACT_ENFORCEMENT_ENABLED | true | Enforce contact policy |
docker build -t mcp-agent-mail .
docker run --rm -p 8765:8765 \
-e HTTP_HOST=0.0.0.0 \
-v agent_mail_data:/data \
mcp-agent-mail
| Tool | Integration |
|---|---|
| NTM | Agent panes coordinate via mail, dashboard shows inbox |
| BV | Task IDs become thread IDs, robot flags inform task selection |
| CASS | Search mail threads across sessions |
| CM | Extract procedural memory from mail archives |
| DCG | Mail notifies agents of blocked commands |
| RU | Coordinate multi-repo updates via cross-project mail |
Jeffrey Emanuel's multi-agent implementation workflow using NTM, Agent Mail, Beads, and BV. The execution phase that follows planning and bead creation. Includes exact prompts used.
Converting markdown plans into beads (tasks with dependencies) and polishing them until they're implementation-ready. The bridge between planning and agent swarm execution. Includes exact prompts used.
Beads Viewer - Graph-aware triage engine for Beads projects. Computes PageRank, betweenness, critical path, and cycles. Use --robot-* flags for AI agents.
Remove telltale signs of AI-generated 'slop' writing from README files and documentation. Make your docs sound authentically human.
Named Tmux Manager - Multi-agent orchestration for Claude Code, Codex, and Gemini in tiled tmux panes. Visual dashboards, command palette, context rotation, robot mode API, work assignment, safety system. Go CLI.
Find opportunities to improve web application code using TanStack libraries (Query, Table, Form, Router, etc.). Avoid man-with-hammer syndrome by applying TanStack after vanilla implementation works.