My Mail MCP

A self-hosted, provider-configurable email MCP server. Yahoo is the initial target. Built with FastMCP 4.1.3, pinned in pyproject.toml and uv.lock. One stateless Python container; no database or application action quota.

Status: mailbox management preview

Implemented: authenticated Streamable HTTP MCP, health endpoint, folder listing, paginated text search, reading, flag updates, moving/copying, archiving, trashing/restoring, permanent deletion, and creating/renaming/deleting user folders. Message references include folder, UID and UIDVALIDITY to reject stale identifiers. Attachment metadata is included; attachment downloads are not implemented yet. Search pagination bounds the returned data, but currently searches all matching UIDs.

Planned: drafts, attachment transfer and GitHub Actions deployment configuration. OAuth (Auth0 JWT validation) is implemented; see Auth0 setup. Cloud Build deployment is configured. Sending is implemented but untested against live Yahoo SMTP. Yahoo reading has been manually verified locally through VS Code Copilot. Mutation tools have automated coverage but have not been tested against a live Yahoo mailbox; other providers and Cloud Run remain unverified.

Related MCP server: Mail-MCP

Tools

With more than one account configured, every tool except list_accounts requires an account id (see Multiple mailboxes); it is optional with one account.

Sending is irreversible. Tools advertise destructiveHint so clients can ask for confirmation; the server also limits messages to 20 recipients and rejects header injection. Set sent_folder on the account if the Sent folder is not detected. The sender is always the configured mailbox.

since (inclusive) and before (exclusive) take YYYY-MM-DD and match whole days in the mail server's time zone, so "today" is since=<today>. Search returns newest UID first (mailbox arrival order, not necessarily the message's Date header). Search totals reflect the initial UID snapshot; messages removed before fetching are omitted and reported in unavailable_uids. limit is 1–100; use next_offset for pagination. Pass the folder, UID and UIDVALIDITY from search to read a message. Reads reject messages over 10 MiB and truncate bodies at 100,000 characters, with body_truncated indicating truncation. Reading leaves flags unchanged.

Modifying a mailbox

Message modifications accept 1–100 distinct positive integer UIDs from the same folder. Always use a fresh search result's uid_validity. Missing UIDs, stale folder versions, invalid destinations, and read-only folders reject the request before changing messages. Concurrent mailbox changes can still occur after these checks.

For example, after searching INBOX, call update_flags with the returned folder, UIDVALIDITY, uids: [<uid>], and read: true or starred: true. Omitted flag fields stay unchanged. To undo a flag change, explicitly pass false.

Archive and Trash are resolved through IMAP special-use flags and standard-name fallbacks. Set archive_folder or trash_folder on the account if discovery is ambiguous or fails. These folders must already exist; they are not created automatically. Trash is recoverable until the provider purges it. Restore uses current UIDs from Trash and defaults to INBOX; the original folder is not recorded.

Moving changes UIDs. Search the destination again before operating on moved or copied messages. The result returns destination and refresh_destination: true; it deliberately does not reuse source UIDs as destination references.

Moves prefer atomic IMAP MOVE. Servers without MOVE must support UIDPLUS for the copy/delete/UID EXPUNGE fallback. Permanent deletion always requires UIDPLUS and expunges only the requested UIDs, never unrelated deleted messages. Unsupported servers fail before writing. Multi-command operations are not transactions: a failed move may leave a copy in the destination, and a failed delete may leave messages marked for deletion. Refresh both folders before retrying; automatic retries can create duplicates. Copies are also not safe to retry automatically.

Folder renaming and deletion require UIDVALIDITY from a search of the folder (including empty search results). Detected/configured system folders and INBOX are protected. Folders with children must be handled from the leaves upward. Delete checks that a folder is empty first; concurrent deliveries are not locked. Folder hierarchy delimiters are returned by list_folders.

Local development

Install uv first. The project defaults to Python 3.12; uv can download it if needed:

uv sync --locked
cp .env.example .env
# Edit .env with your own mailbox and a random MCP token of at least 32 characters.
uv run --locked my-mail-mcp

uv manages .venv automatically; shell activation is unnecessary. Development dependencies are included by default. Commit uv.lock to keep installations reproducible. To run checks:

uv run --locked pytest -q
uv run --locked ruff check src tests

Add dependencies with uv add <package> or uv add --dev <package>. Use uv lock --upgrade to intentionally update locked versions.

Never commit .env. Generate a token with openssl rand -hex 32. Create a dedicated Yahoo app password in Yahoo Account Security. The server refuses to start without mailbox credentials and an MCP token, or when configured with the known placeholder credentials. Replace the GCP placeholders before deploying. Clients connect to /mcp/ with Authorization: Bearer <MCP_AUTH_TOKEN>. GET /health checks the process, without connecting to the mailbox. Bearer authentication is an initial integration option; browser-based connector OAuth is available for browser-based connectors such as ChatGPT; see Auth0 setup.

VS Code Copilot setup

Start the server separately, then create .vscode/mcp.json:

{
  "inputs": [
    {
      "id": "mail-mcp-token",
      "type": "promptString",
      "description": "MCP_AUTH_TOKEN from your local .env",
      "password": true
    }
  ],
  "servers": {
    "my-mail-mcp": {
      "type": "http",
      "url": "http://localhost:8080/mcp/",
      "headers": {"Authorization": "Bearer ${input:mail-mcp-token}"}
    }
  }
}

Enter the same token used by the server when prompted. Client configuration formats vary: the example uses VS Code's servers format and interactive inputs. VS Code also supports portable workspace-root .mcp.json configurations with mcpServers, but those do not support VS Code input variables. Local credential-bearing configurations are ignored by Git. Ask Copilot to list folders, then read your latest email.

Configuration

Environment variables take precedence over .env. IMAP certificate and hostname verification remain enabled, using system trust plus Certifi's CA bundle. The server binds to all interfaces; use localhost for local clients and HTTPS when exposing it remotely. The bearer credential grants access to this mailbox.

Multiple mailboxes

Mailboxes are configured with MAIL_ACCOUNTS, a JSON list with one entry per mailbox. In .env, put it inside single quotes (multi-line is fine). On Cloud Run it is the contents of a Secret Manager secret (see the deployment guide).

Single Yahoo mailbox (hosts default to Yahoo, so only three fields are needed):

MAIL_ACCOUNTS='[{"id":"yahoo","username":"you@yahoo.com","password":"yahoo-app-password"}]'

Two Yahoo mailboxes:

MAIL_ACCOUNTS='[
 {"id":"personal","username":"you@yahoo.com","password":"app-password-1"},
 {"id":"family","username":"family@yahoo.com","password":"app-password-2"}
]'

Yahoo and Gmail (non-Yahoo providers override the hosts):

MAIL_ACCOUNTS='[
 {"id":"yahoo","username":"you@yahoo.com","password":"yahoo-app-password"},
 {"id":"gmail","username":"you@gmail.com","password":"gmail-app-password",
  "imap_host":"imap.gmail.com","smtp_host":"smtp.gmail.com","save_sent_copy":false}
]'

To add a mailbox, append an entry with a unique id and restart the server.

Required per account: id (letters, digits, _, ., -), username, password. Optional: imap_host, imap_port, smtp_host, smtp_port, smtp_starttls, archive_folder, trash_folder, sent_folder (defaults match Yahoo) and save_sent_copy (default true; set false for Gmail, whose SMTP files sent mail itself).

• Call list_accounts, then pass account to every other tool. Without it the call is rejected, so mail is never touched in the wrong mailbox. UIDs are per account. With one account, account can be omitted. Example, today's unread mail in Gmail: search_messages with {"account": "gmail", "since": "2026-10-26", "unread_only": true}.

• With several accounts, use the folder names from list_folders for that account; they differ by provider (Inbox on Yahoo, INBOX and [Gmail]/Trash on Gmail).

• A bad entry (duplicate or invalid id, placeholder password) stops the server at startup.

• At most 3 simultaneous IMAP connections per account per server instance; extra requests wait up to a minute. The cap is not shared across instances, so Cloud Run scale-out (up to _MAX_INSTANCES, default 3) can reach that many times 3 connections. Lower _MAX_INSTANCES if your provider rejects logins during scale-out.

• Logs show the account id (not the address): imap account=gmail op=search_messages ....

• Moving or copying between accounts is not supported.

• Gmail needs 2-Step Verification and an app password. Its folders are labels ([Gmail]/All Mail), so archive behaves differently from Yahoo; Gmail has not been tested beyond reading, searching and folder listing.

Container / Cloud Run

docker build -t my-mail-mcp:local .
docker run --rm --name my-mail-mcp-local --env-file .env -p 127.0.0.1:8080:8080 my-mail-mcp:local

Cloud Run supplies PORT. Mount MAIL_ACCOUNTS and MCP_AUTH_TOKEN as Secret Manager references (a single mailbox is a one-entry MAIL_ACCOUNTS list). The service account needs access only to those secrets. Cloud Run IAM and the application's bearer authentication are separate layers; client access must be configured accordingly. cloudbuild.yaml runs checks, builds and pushes to Artifact Registry, then deploys Cloud Run with Secret Manager references. Follow the deployment guide for one-time setup and GitHub triggers. Start with the deployment guide, then enable OAuth with Auth0 setup if you want ChatGPT access.

OAuth for ChatGPT via Auth0 is documented in Auth0 setup. The static bearer token keeps working alongside it.

A deployment can serve several mailboxes (see below). Change IMAP settings for another compatible provider; providers requiring OAuth need an additional authentication implementation. Yahoo/provider limits and cloud hosting charges still apply.

Verification and release scope

Tests use mocked mailboxes and do not need Yahoo credentials. CI checks Python 3.11/3.12, lint, formatting, package build, and Docker build. GitHub CI does not deploy or publish. The Cloud Build configuration deploys when explicitly submitted or attached to a configured trigger. Local Docker validation passed on Linux ARM64: all 68 tests in the builder container, non-root runtime, HTTP health/authentication, discovery of the tools, and live Yahoo folder listing. No live mail mutations were tested. Cloud Run runtime validation remains pending.

This preview exposes read and write operations. Mutation tools advertise their write/destructive behavior to MCP clients. Permanent deletion is irreversible; use Trash for recoverable deletion. Email content is untrusted input and must never be treated as instructions authorizing mailbox changes. No message database is maintained; content is returned to your MCP client, which controls its own retention.

License

MIT.