MCP Agent Mail
A coordination layer for coding agents that provides memorable identities, inbox/outbox messaging, searchable message history, and file lease management to prevent conflicts. Uses Git for human-auditable artifacts and SQLite for fast queries, enablin
What is MCP Agent Mail?
MCP Agent Mail is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to coordination layer for coding agents that provides memorable identities, inbox/outbox messaging, searchable message history, and file lease management to prevent conflicts. uses git for human-auditabl...
A coordination layer for coding agents that provides memorable identities, inbox/outbox messaging, searchable message history, and file lease management to prevent conflicts. Uses Git for human-auditable artifacts and SQLite for fast queries, enablin
This server falls under the Coding Agents category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- A coordination layer for coding agents that provides memorab
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx mcp-agent-mailConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use MCP Agent Mail
MCP Agent Mail is a coordination layer for multiple coding agents that need to communicate, share context, and avoid stepping on each other's files. It provides each agent with a memorable identity, an inbox/outbox messaging system backed by SQLite FTS5 for fast search, and a file lease mechanism that detects and prevents concurrent edit conflicts. All messages and agent profiles are committed to a Git repository as human-readable markdown, giving human overseers an auditable trail of every inter-agent conversation and file reservation.
Prerequisites
- Python 3.11+ and the 'uv' package manager installed
- Git installed and available on the system PATH
- An MCP-compatible agent runtime such as Claude Code, Codex, or Gemini CLI
- SQLite 3.x (included with Python) for the FTS5 index
- Optional: Docker for containerized deployment
Run the automated installer
The installer script sets up a Python 3.14 virtual environment with uv, installs all dependencies, starts the HTTP server on port 8765, generates a bearer token, and creates the 'am' shell alias for future launches.
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh?$(date +%s)" | bash -s -- --yesStart the server
After installation, launch the server at any time using the 'am' alias created by the installer. The server binds to 127.0.0.1:8765 by default.
amRegister a project with the server
Before agents can exchange messages about a project, register the project's absolute path so the server knows where to create the Git-backed mailbox.
uv run python -m mcp_agent_mail.cli projects ensure /abs/path/to/your/projectConfigure your MCP client to connect
Add mcp-agent-mail to your agent's MCP server list, pointing to the local HTTP endpoint with the generated bearer token from the .env file.
Register an agent identity via MCP
Each agent registers itself with a name and role at session start using the register_agent tool. This creates an agent profile committed to Git.
Reserve files before editing
Before modifying a file, call file_reservation_paths with the paths or glob patterns to signal intent. The server detects conflicts if another agent holds an exclusive reservation.
Send and fetch messages between agents
Use send_message to post updates (with optional thread_id and attachments) and fetch_inbox to poll for incoming messages. release_file_reservations frees locks when editing is complete.
MCP Agent Mail Examples
Client configuration
Add this to your Claude Desktop or Claude Code MCP configuration. Replace the bearer token value with the one generated during installation (found in ~/.mcp_agent_mail.env).
{
"mcpServers": {
"mcp-agent-mail": {
"command": "uv",
"args": ["run", "python", "-m", "mcp_agent_mail.server"],
"env": {
"HTTP_HOST": "127.0.0.1",
"HTTP_PORT": "8765",
"HTTP_BEARER_TOKEN": "your-generated-token",
"STORAGE_ROOT": "~/.mcp_agent_mail_git_mailbox_repo",
"LOG_LEVEL": "INFO"
}
}
}
}Prompts to try
Use these in a multi-agent setup where each agent has the mcp-agent-mail server connected.
- "Register me as agent 'backend-agent' working on the API module"
- "Reserve src/api/routes.py exclusively before I start editing it"
- "Send a message to 'frontend-agent' saying the /users endpoint schema has changed"
- "Fetch my inbox and summarize any unread messages"
- "Search messages for any thread mentioning database migrations"
- "Release my reservation on src/api/routes.py now that I'm done"Troubleshooting MCP Agent Mail
Server fails to start with 'address already in use' on port 8765
Another process is using port 8765. Change the port with: uv run python -m mcp_agent_mail.cli config set-port 9000, then update the HTTP_PORT in your MCP client config accordingly.
Agents receive 401 Unauthorized when calling MCP tools
The bearer token in the MCP client config must match the HTTP_BEARER_TOKEN in .env. Re-run 'am' to see the current token, or open ~/.mcp_agent_mail.env to copy the generated value.
File reservation conflicts are not being detected
Ensure the project path was registered via 'projects ensure' before agents started reserving files. All agents must be connected to the same server instance (same host:port) for conflict detection to work across sessions.
Frequently Asked Questions about MCP Agent Mail
What is MCP Agent Mail?
MCP Agent Mail is a Model Context Protocol (MCP) server that coordination layer for coding agents that provides memorable identities, inbox/outbox messaging, searchable message history, and file lease management to prevent conflicts. uses git for human-auditable artifacts and sqlite for fast queries, enablin It connects AI assistants to external tools and data sources through a standardized interface.
How do I install MCP Agent Mail?
Follow the installation instructions on the MCP Agent Mail GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with MCP Agent Mail?
MCP Agent Mail works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is MCP Agent Mail free to use?
Yes, MCP Agent Mail is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
MCP Agent Mail Alternatives — Similar Coding Agents Servers
Looking for alternatives to MCP Agent Mail? Here are other popular coding agents servers you can use with Claude, Cursor, and VS Code.
Dify
★ 142.2kProduction-ready platform for agentic workflow development.
Ruflo
★ 54.0k🌊 The leading agent orchestration platform for Claude. Deploy intelligent multi-agent swarms, coordinate autonomous workflows, and build conversational AI systems. Features enterprise-grade architecture, self-learning swarm intelligence, RAG integrat
Goose
★ 45.7kan open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM
Antigravity Awesome Skills
★ 38.3kInstallable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.
AgentScope
★ 25.5kBuild and run agents you can see, understand and trust.
Serena
★ 24.5kA coding agent toolkit that provides IDE-like semantic code retrieval and editing tools, enabling LLMs to efficiently navigate and modify codebases using symbol-level operations instead of basic file reading and string replacements.
Browse More Coding Agents MCP Servers
Explore all coding agents servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up MCP Agent Mail in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use MCP Agent Mail?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.