Open Agent Email MCP

Install

Works in

• Claude Code
• Cursor
• SourceCraft
• Koda
• Coddy

Manual install

git clone https://github.com/Anil-matcha/open-agent-email.git && cd open-agent-email && ./scripts/dev.sh

What it does

Open Agent Email is a Python server that gives AI agents real mail addresses. It starts with `./scripts/dev.sh` or Docker Compose. On first start it creates an admin key and an encryption key, brings up the API on port 8000 and an SMTP listener on port 2525. The administrator creates an agent inbox and an access key for it, and from there the agent reads mail, replies in the same thread, forwards messages and writes new ones through REST, the Python and TypeScript clients, the `oae` command-line tool or MCP. An incoming message is received by the SMTP listener and first goes through a threat scanner. It looks in the text and HTML for commands such as "ignore previous instructions", hidden text (`display:none`, zero font size), ChatML delimiters and data leaks through markdown images, and it decodes and checks base64. A suspicious message lands in a manual approval queue. With `hitl_enabled` on, which is the default, outgoing mail goes into the queue too: a person approves or rejects it in the dashboard or through a link in an email. Outgoing mail leaves through an upstream SMTP relay such as Amazon SES, Resend, SendGrid, Postmark or Gmail, while mail between inboxes on the same server needs no relay. The MCP server sits at `/mcp/rpc` and accepts the same key in the Authorization header. It has 96 tools, and the set depends on the key: an inbox key works only with its own inbox, an admin key manages inboxes, domains, keys and server settings, and a reviewer key sees only the approval queue. The `get_recent_otp` tool pulls a 4–8 digit verification code from recent messages and never returns the message body.

Who it is for. For developers who want to give an agent in Claude Code or Cursor its own mail address for sign-ups, correspondence and notifications, and who are ready to deploy and maintain a server themselves.

Example request

Start Open Agent Email locally, create the inbox hello@agents.example.com with approval for outgoing mail and connect it to Claude Code over MCP

MCP

Transport

http

Authentication

API key

Limitations

• The repository has no license file, although the description names Apache 2.0. The author has not specified a license, so rights to use and copy are undefined; check with the author.
• The project is under active development. The author warns that the mail path has had limited testing against live providers and asks you to read the operations guide before putting real traffic on it. The check records of October 15, 2026 come from a laptop, not a staging environment: 757 tests passed on both SQLite and PostgreSQL 16.15.
• By default data sits in SQLite inside the Docker volume `oae-data`. The encryption key for relay passwords, webhook secrets and DKIM keys is stored there too: lose the volume and the key, and the saved secrets cannot be read.
• To receive mail from the internet you have to map port 2525 to port 25, and to send outward you have to configure a relay in the settings section.
• The TypeScript client is built from the `sdks/typescript` directory of the repository; the author does not publish it to a package registry. The Python client installs from `sdks/python`.

How to disable. Remove the MCP connection with `claude mcp remove open-agent-email` or delete the `open-agent-email` section from `.cursor/mcp.json`. Revoke the inbox key in the dashboard so it stops working. `docker compose down` stops the Docker server, and the `oae-data` volume with mail, keys and the database stays on disk until you delete it separately.

README in short

The repository holds the server, a Next.js dashboard, Python and TypeScript clients and an example WebSocket event listener. Documentation covers a quickstart, a reference with the MCP tool catalog, an operations guide, error codes and monitoring rules for Prometheus. There are many tests: the server ones check the OpenAPI contract and parity between MCP and REST, and the client ones cover webhooks and pagination. The operations guide ends with a table of exercises to pass on a staging environment before real mail is switched on.