home / mcp / mcp mail mcp server

MCP Mail MCP Server

Provides a mail-like coordination layer for coding agents with inbox/outbox, global search, and file reservations.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "jleechanorg-mcp_mail": {
      "url": "http://127.0.0.1:8765/mail"
    }
  }
}

MCP Mail provides a mail-like coordination layer for coding agents. It gives agents memorable identities, an inbox/outbox, global and project-scoped message history, and lightweight file reservations to signal intent. You interact with MCP Mail through a server that exposes a simple HTTP endpoint and a set of practical tools to register agents, send and receive messages, search conversations, and manage reservations across multiple projects.

How to use

To coordinate with MCP Mail, you use a client that can talk to the MCP HTTP server. Typical workflows include registering your agent, sending messages to other agents, reading your inbox, and using search to find past discussions. You can work across multiple projects because agents have globally unique identities and messages can be addressed to any agent by name.

How to install

Prerequisites you need before installing MCP Mail:

- Python 3.11 (recommended) and a working internet connection

- The uv runtime (used to run Python in a lightweight virtual environment)

Follow one of the installation paths below to set up the MCP Mail server locally.

# Quick install from PyPI (recommended)
pip install mcp-mail

# One-line installer (sets up everything)
curl -fsSL https://raw.githubusercontent.com/jleechanorg/mcp_mail/main/scripts/install.sh | bash -s -- --yes

# After install, the server listens on http://127.0.0.1:8765/mail

# Manual installation (step-by-step)
# Install uv if you don’t have it
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# Clone the repository
git clone https://github.com/jleechanorg/mcp_mail
cd mcp_mail

# Create a Python 3.11 virtual environment and install dependencies
uv python install 3.11
uv venv -p 3.11
source .venv/bin/activate
uv sync

# Start the MCP server
scripts/run_server_with_token.sh

# The server will serve at http://127.0.0.1:8765/mail

Configuration and start tips

The MCP Mail server exposes a rich set of configuration options via environment variables. Key settings include the HTTP host/port, authentication, storage location, and tool exposure mode. You can adjust the HTTP port, start flags, and storage behavior to fit your environment.

Common start patterns you may encounter after installation:

# Start server with default settings
uv run python -m mcp_agent_mail.http

# Start server on a custom port
HTTP_PORT=9000 uv run python -m mcp_agent_mail.http --host 127.0.0.1 --port 9000

# Serve the HTTP API with an explicit path
HTTP_PATH=/mcp/ uv run python -m mcp_agent_mail.http --host 127.0.0.1 --port 8765

# To start from a ready-to-run shell script
scripts/run_server_with_token.sh

# The web UI is accessible at http://127.0.0.1:8765/mail

Security and data handling

MCP Mail uses a dual persistence model: a human-readable Git repository archive for messages and a SQLite database for fast indexing and search. You can enable or disable project-local storage, use a global mailbox, and protect the server with bearer tokens or JWTs. Message bodies are sanitized and rendered safely, and a set of redaction presets helps protect sensitive data when exporting or sharing archives.

Important security concepts to understand include: HTTP authentication options (Bearer tokens or JWT), RBAC controlling reader vs writer access, and data export safeguards (scrub presets and signature verification). When exposing beyond localhost, enable proper authentication and TLS termination through a reverse proxy.

Troubleshooting and notes

If you encounter issues, check the following common areas

- Port conflicts: choose a different HTTP port and restart the server

- UI access: ensure HTTP_ALLOW_LOCALHOST_UNAUTHENTICATED is set for local dev; otherwise provide a valid token

- Data visibility: ensure you are using the correct project key and agent names; messages are stored per-project in Git archives and in SQLite for search

Available tools

health_check

Lightweight readiness probe for server health and runtime environment

ensure_project

Create or ensure a project exists in the MCP workspace

register_agent

send_message

Send a new message to one or more recipients, creating inbox/outbox copies and a canonical message

fetch_inbox

Read an agent's inbox with optional filters like limit and since timestamp

search_messages

Perform FTS5-based search across subject and body for a project

share wizard

Launch an interactive deployment wizard to export and deploy a static mailbox bundle

share export

Export a project's mailbox to a static HTML bundle for offline viewing

share verify

Verify the integrity and signatures of an exported bundle

summarize_thread

Create a concise summary of a thread's key points and actions

file_reservation_paths

Declare advisory file reservations to signal editing intent

release_file_reservations

Release active file reservations for an agent

guard install

Install a pre-commit guard to enforce reservation rules in a repo

config set-port

Change the HTTP server port in the environment configuration

guard status

Check the status of pre-commit guards for a repository