MCP Agent Mail provides an HTTP-only coordination layer for coding agents, offering a mailbox-style interface with inbox/outbox, searchable histories, and advisory file reservations (leases) to coordinate access to files and globs. The server is Python-based and runs under the uv runner, exposing endpoints to register agent identities, send and fetch messages (including Git-flavored Markdown with images), and query or summarize conversations. Agents can also place file reservations to signal intent and avoid conflicts. Once running, you can interact with the server via the REST/HTTP API exposed by the FastMCP server or through provided CLI helpers that wire up to the mailbox, messages, and leases features. Typical workflows include registering identities, sending messages to other agents, attaching artifacts, searching conversations, and applying/advising file leases before destructive edits.

Prerequisites:

• Python 3.14+ and a Python virtual environment tool (venv or similar)
• uv (Python UV) installed or installable via the project’s install script
• Git

Installation steps:

1. Clone the repository git clone https://github.com/Dicklesworthstone/mcp_agent_mail.git cd mcp_agent_mail

2. Create and activate a Python 3.14 virtual environment python3.14 -m venv .venv source .venv/bin/activate # on Unix-like systems

   Windows: ..venv\Scripts\activate

3. Install uv (the UV runner) and dependencies

   If the installer script is provided, you may run it as described in the README; otherwise install uv manually

   pip install uv pip install -r requirements.txt # if a requirements file exists

4. Verify installation and run a quick detection/setup (as described in the repo’s docs)

   Start the MCP Agent Mail server (see next step for the exact run command)

5. Start the server uv run python -m mcp_agent_mail.cli

   Alternatively, if using the recommended installer script, use the provided am alias to start the server

6. Optional: configure port and token

   • The default port is 8765; to override, set PORT in your environment or pass a config option as described in the README
   • A bearer token is generated and stored in .env during setup; ensure it is loaded in your shell before making requests

Notes:

• The project is designed to be initialized via a one-line installer in the README, which handles environment setup, dependencies, and server startup. If you are setting up manually, ensure uv is installed and available in your PATH.

Tips and common issues:

• If you encounter port conflicts, specify a different port (default 8765) using the --port option or by setting PORT in your environment.
• The server uses a bearer token for authentication; store and load the token securely (see .env handling in the installer notes).
• The system relies on a Git-backed mailbox and SQLite for indexing; ensure Git access and write permissions are available in the working directory.
• If you are integrating with Beads or companion tooling, confirm the environment is set up per the README’s integration steps to ensure cross-tool compatibility.
• The installer mentions alias scripts (am) and additional tools (Beads Rust, bv); these are optional enhancements and can be skipped with corresponding flags if you don’t need them.