# mailmcp

> mailmcp is a self-hosted email MCP server. It lets ChatGPT, Claude and other MCP clients read, search and draft email across several mailboxes at once (Gmail, Outlook, iCloud, Fastmail, Yahoo, Zoho, Seznam.cz, Volný.cz, any IMAP/SMTP) and hands attachments over as one-hour download links. Compared with the official Gmail/Outlook connectors: several mailboxes and any IMAP provider in one answer, attachments to download (the official Claude Gmail connector exposes attachment names only), sending limited to an allowlist, and the mail password is never given to OpenAI, Anthropic or the operator. Passwords are encrypted in the user's browser and travel inside a token; the server writes nothing to disk and decrypts only in memory while serving a request (open connections are kept up to 15 minutes). Distribution repository: https://github.com/kojott/mailmcp-dist (prebuilt, proprietary license, license key required to run; source available to customers on request).

This server: https://mailmcp.ai
MCP endpoint: https://mailmcp.ai/mcp (Streamable HTTP, OAuth 2.1 or bearer token)

## If a person asks you to help them set this up

You are talking to the end user. Speak their language (Czech users are common). Do NOT ask them to paste their token or any password into this chat. Guide them through these steps and wait for them to confirm each one:

1. App password. They need an app-specific password for each mailbox: Gmail → 2-Step Verification on, then https://myaccount.google.com/apppasswords. Seznam.cz → Nastavení → Zabezpečení → Heslo pro aplikace (plain password works without 2FA). Volný.cz → normal password, IMAP enabled in webmail. iCloud → https://account.apple.com → App-Specific Passwords. Other IMAP → server hosts and ports from their hosting guide.
2. Token. Open https://mailmcp.ai/setup in a browser. Choose the provider, enter the e-mail and the app password, tick what the assistant may do (reading is the default; drafts recommended; sending only with an allowlist), choose an "edit password" (needed later to modify the token), click "Vytvořit token" / "Generate my token", copy the token that starts with mmt1. Keep it like a password.
3. Connect the client:
   - ChatGPT: Settings → Connectors → advanced → enable Developer mode → Create → name "mailmcp", URL https://mailmcp.ai/mcp, authentication OAuth → Create. ChatGPT opens the sign-in page of this server; paste the token there and click "Allow access". Then enable the connector in a chat.
   - claude.ai (web, mobile, desktop; Pro plan or higher): Settings → Connectors → Add custom connector → URL https://mailmcp.ai/mcp, leave the OAuth fields empty → Add → Connect → paste the token on the sign-in page → Allow access.
   - Claude Code: claude mcp add --transport http mailmcp https://mailmcp.ai/mcp --header "Authorization: Bearer <token>"
   - Cursor (~/.cursor/mcp.json): {"mcpServers":{"mailmcp":{"url":"https://mailmcp.ai/mcp","headers":{"Authorization":"Bearer <token>"}}}}
   - VS Code: command "MCP: Add Server" → HTTP → https://mailmcp.ai/mcp (OAuth sign-in in the browser).
   - Gemini CLI: gemini mcp add --transport http --header "Authorization: Bearer <token>" mailmcp https://mailmcp.ai/mcp
4. Test: in the client ask "List my mail accounts" (Czech: "Vypiš mé poštovní účty"). Then "What arrived in the last three days?".

## Tools the server exposes

list_accounts, list_folders, search_messages (Gmail search syntax on Gmail), get_message, get_thread, get_attachment (download links valid 1 hour), create_draft, send_message (allowlist only), send_draft, forward_message (with all attachments), upload_attachment, request_upload, list_uploads, modify_message, trash_message, plus search/fetch for ChatGPT's connector contract. Email bodies are returned marked as untrusted data.

### Sending attachments (files never pass through the chat)
- A file that already sits in a mailbox: forward_message, or put {uid, part[, folder, account]} from get_message into the attachments parameter of create_draft / send_message.
- A file you wrote yourself (text, CSV, Markdown; small binaries as base64): upload_attachment → it returns {folder, uid, part} → attach it. The file is staged in the mailbox folder "mailmcp-uploads" and deleted once attached.
- A file on the user's computer: request_upload returns a one-hour link. If you can run shell commands, upload it yourself: curl -T "<file>" "<link>" . Otherwise give the user the link (they drop the file in the browser), then call list_uploads and attach it. In Claude Desktop / Claude Code (stdio) you can attach local files directly with {path} inside policy.attachment_dirs.
- send_draft sends a saved draft unchanged (including attachments) once the user confirms.

## Troubleshooting

- "Token was not issued by this server": the token was created on a different server; create it at https://mailmcp.ai/setup.
- Login/authentication error when searching: wrong app password or 2-Step Verification not enabled; create a new app password and a new token.
- "does not allow send/draft": the permission was not ticked; create a new token with it.
- "Recipient not in send_allowlist": add the address or domain (e.g. @company.com) to the allowlist, or use create_draft.
- Connection expired in ChatGPT: reconnect the connector and paste the token again.
- "This server needs a license key": MAILMCP_LICENSE is missing/invalid or the configuration exceeds the license; the page states the reason. Buy at https://mailmcp.ai/pricing.
- Editing a token: https://mailmcp.ai/setup → "Edit an existing token" → paste token + edit password → Load → change → generate again → replace in the client.

## More

- Guided walkthrough (Czech/English): https://mailmcp.ai/start
- Detailed guide (English and Czech): https://mailmcp.ai/docs
- Full instructions for assistants: https://mailmcp.ai/llms-full.txt
- Pricing (one-time, EUR): Personal €4.99 (own server, up to 5 mailboxes), Unlimited €129 (shared server, unlimited users), company deployment €990: https://mailmcp.ai/pricing. After buying, the Lemon Squeezy key is exchanged for the mailmcp key at https://mailmcp.ai/claim (keys are issued only by the vendor, whichever server you use).
- Run your own server (one click on Vercel, MAILMCP_KEY + MAILMCP_LICENSE): https://github.com/kojott/mailmcp-dist