MCP Agent Mail

You set up and run MCP Agent Mail to coordinate multiple coding agents through a central, auditable, HTTP‑based server. It provides identities, asynchronous messaging, searchable history, and advisory file reservations to avoid conflicts, backed by Git for human review and SQLite for fast queries.

How to use

You can onboard agents, send messages, reserve files, and track progress across one or more codebases. Start by registering each agent with a project key, then send messages within threads to collaborate on specific tasks. Use file reservations before editing to declare intent and prevent conflicts. Review inboxes, acknowledge messages, and summarize conversations to keep everyone aligned. When needed, humans can send high-priority Overseer messages to steer workloads, while Beads manages task planning and dependencies.

Use the web UI to browse projects, read threads, search conversations, view file reservations, and attach artifacts. Read and summarize threads, or export a static mailbox bundle for auditors or offline review. Beads and Beads Viewer help you prioritize tasks and understand dependencies, while Overseer messages let humans inject urgent guidance into the workflow.

How to install

Prerequisites: you need Python 3.14 and a supported runtime for the MCP HTTP server. You also typically use the uv tooling to run the server.

# One-line installer example (optional). This installs dependencies and starts MCP Agent Mail
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yes

If you prefer a manual setup, clone the repository, create a Python 3.14 virtual environment, install dependencies, and start the server using the HTTP entry points described below.

uv run python -m mcp_agent_mail.cli serve-http
uv run python -m mcp_agent_mail.http --host 127.0.0.1 --port 8765

Configuration and runtime details

The server runs over HTTP and is configurable via environment variables and the local .env file. Common settings include the storage root for per-project data, the host/port for the HTTP server, and optional authentication like JWT or a static bearer token. You can also enable local-host bypass for development.

# Example minimal .env entries
STORAGE_ROOT=/path/to/mailbox
HTTP_HOST=0.0.0.0
HTTP_PORT=8765
HTTP_PATH=/mcp/
HTTP_BEARER_TOKEN=your-token-here
HTTP_ALLOW_LOCALHOST_UNAUTHENTICATED=true

Security and data integrity

Messages are stored in Git with per-message Markdown bodies and optional attachments. A SQLite database powers fast全文搜索 (FTS5). You can export static bundles for audits with cryptographic signing and optional age encryption. HTML content is sanitized to prevent script execution, and access can be protected with JWT or a bearer token.

# Example verification commands for a static export
uv run python -m mcp_agent_mail.cli share verify ./my-bundle
uv run python -m mcp_agent_mail.cli share decrypt bundle.zip.age --identity ~/.age/key.txt

Troubleshooting and tips

If the UI or API is unavailable, check that the server is running and the port is correct. Review environment variables for authentication. For port conflicts, adjust the port in the startup commands or via config. If a memory issue or large dataset arises, consider enabling chunking or pruning data before export.

# Quick health check (example)
uv run python -m mcp_agent_mail.cli doctor check

Typical use cases

Coordinate multiple agents across frontend/backend workstreams, protect critical migrations with exclusive file reservations, and inspect a directory of active agents and activity. Discover relationships between projects, thread conversations into coherent summaries, and maintain auditable artifacts for governance.