OpenViSTAI · Agents · Blockchain · Crypto
Submit a project
Menu
Agent Frameworks

MCP Agent Mail

MCP Agent Mail is a Python, HTTP-only FastMCP server that provides coding agents with identities, inboxes and outboxes, searchable message history, an agent directory, and voluntary file-reservation leases. It uses Git for human-auditable artifacts and SQLite for indexing and queries.

Explore the practical guide ↓

Independent OpenViST project profile, based on linked sources.

MCP Agent Mail — OpenViST project profile in Agent Frameworks.
OpenViST project illustration. See the linked sources for product details.
Understand the project

Practical overview

When it fits

Consider it when parallel coding agents need a shared message history and a way to signal intended file changes. The repository says this Python implementation is no longer maintained and directs new installs to its Rust successor.

Who it is for

  • Teams running multiple coding agents across one codebase or related repositories.
  • Users of FastMCP clients and CLI coding-agent tools seeking asynchronous messaging and shared editing-intent signals.

Documented uses

  • Register agent identities and inspect active agents and their activity.
  • Send, receive, thread, search and summarize agent conversations.
  • Declare file or glob reservations to communicate intended edits.
  • Coordinate agents across one repository or link agents working in separate repositories.
Before you choose

Requirements & limits

  • The Python version is explicitly superseded and no longer maintained; the README recommends mcp_agent_mail_rust for new installs.
  • The server is HTTP-only and built with FastMCP; the documented stack also uses Git and SQLite.
  • File leases are voluntary and advisory, rather than a guarantee against conflicting edits.
  • The installer creates a Python 3.14 virtual environment and installs Beads Rust and Beads Viewer by default; it can replace an existing Go-based bd installation.
  • The README names Claude Code, Codex, Gemini CLI and Factory Droid as example clients or tools.

Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.

Source-based practical guide

Install the Python MCP Agent Mail server

Set up the Python server and its supported agent-tool integrations.

Before you start

  • The README provides a one-line installer that installs dependencies, creates a Python 3.14 virtual environment, configures detected agent-tool integrations, and starts the HTTP server.

Steps

  1. Run the README’s one-line installer with --yes.

  2. If desired, add documented installer flags such as --dir , --project-dir , --no-start, --port , or --token ; use --skip-beads or --skip-bv to opt out of those installations.

Expected outcome

The installer sets up the environment and integrations and, unless configured otherwise, starts the MCP HTTP server on port 8765 and prints a masked bearer token.

Guide limitations

  • This Python version is superseded and no longer maintained; the README recommends the Rust version for new installs.
  • The installer replaces the Go Beads bd command with Beads Rust br and creates a bd alias, unless Beads installation is skipped.
  • This guide covers setup only; it does not document a complete agent coordination workflow.
Documentation 1 ↗
Source-based practical guide

Register an agent and coordinate work in one repository

Set up an agent identity, signal file-edit intent, and exchange messages for a repository.

Before you start

  • An MCP Agent Mail server and client access to its tools and resources.
  • The repository’s absolute path to use as project_key.

Steps

  1. Call ensure_project, then call register_agent with the repository’s absolute path as project_key.

  2. Before editing, call file_reservation_paths with the project key, agent name, and the file or glob patterns to reserve; the README gives src/** as an example.

  3. Send a message with send_message, optionally using a thread ID; check for incoming messages with fetch_inbox and acknowledge them with acknowledge_message.

Expected outcome

The agent has a registered identity, can declare advisory file reservations, and can coordinate through inbox messages and threads.

Guide limitations

  • File reservations are advisory signals, not guarantees that conflicting edits are prevented.
  • The README’s example uses a reservation TTL and exclusive flag, but reservations do not enforce that agents avoid the files.
  • The README notes that inbox and thread resource reads can require the registration token unless the MCP session is already authenticated as the agent.
Documentation 1 ↗
Evidence and transparency

Sources & review

Official repository ↗Guide documentation ↗
Source record details
Source availability
Active
Sources checked
16 October 2026
Original website title
Dicklesworthstone/mcp_agent_mail · Official homepage title · retained in its source language
How we review sourcesSuggest a correction

Related options

mcp_agent_mail_rust — Named by the repository as the successor to this superseded, no-longer-maintained Python version.