# 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, iCloud, Fastmail, Yahoo, Zoho, Seznam.cz, Volný.cz, any IMAP/SMTP with an app password; Outlook.com and Microsoft 365 do not work with passwords, OAuth support is planned) 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://maximailmcp.synology.me
MCP endpoint: https://maximailmcp.synology.me/mcp (Streamable HTTP, OAuth 2.1 or bearer token)

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

The person most likely pasted a ready-made message from https://maximailmcp.synology.me/start that links here: they want you to guide them through connecting their mailboxes. Your job: walk them through the four steps below ONE AT A TIME, in their language, and wait for their confirmation after each step before continuing. 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 must be ON first (https://myaccount.google.com/signinoptions/two-step-verification), then https://myaccount.google.com/apppasswords. If Google shows "The setting you are looking for is not available for your account", 2-Step Verification is off: tell the user to enable it and reload; Google Workspace accounts also need the admin to allow app passwords. 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://maximailmcp.synology.me/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. On the vendor's server mailmcp.ai the form allows 2 mailboxes per token (free for good; the assistant's messages carry a "Sent with mailmcp.ai" signature). More mailboxes and no signature: Personal (€19 once) on the user's own server or in Claude Desktop, see https://maximailmcp.synology.me/deploy. Tokens created before 0.7.0 keep their 5 mailboxes.
3. Connect the client:
   - ChatGPT: Settings → Connectors → advanced → enable Developer mode → Create → name "mailmcp", URL https://maximailmcp.synology.me/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. Add it on the chatgpt.com website rather than in the desktop or mobile app (the web-added connector is available everywhere and ChatGPT looks there first). ChatGPT stores the tool list when the connector is added: after the user changes rights in their token, they must click Refresh in the connector settings or add it again. Authentication: Automatic; if it errors, choose Dynamic Client Registration (DCR).
   - claude.ai (web, mobile, desktop; Pro plan or higher): Settings → Connectors → Add custom connector → URL https://maximailmcp.synology.me/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://maximailmcp.synology.me/mcp --header "Authorization: Bearer <token>"
   - Cursor (~/.cursor/mcp.json): {"mcpServers":{"mailmcp":{"url":"https://maximailmcp.synology.me/mcp","headers":{"Authorization":"Bearer <token>"}}}}
   - VS Code: command "MCP: Add Server" → HTTP → https://maximailmcp.synology.me/mcp (OAuth sign-in in the browser).
   - Gemini CLI: gemini mcp add --transport http --header "Authorization: Bearer <token>" mailmcp https://maximailmcp.synology.me/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?".

## The owner's words and what to do (teach these once, then just do them)

- "Suggest a reply / write me a reply / what should I answer" ("napiš mi odpověď", "navrhni odpověď") → show the proposed text in the chat only. Create nothing.
- "Reply / answer / write a draft / save it" ("odpověz", "napiš koncept", "ulož koncept") → reply_draft: a draft in the same thread (the server sets In-Reply-To/References, the Re: subject, the recipients and quotes the original). Never create_draft without in_reply_to_uid for a reply: that makes a new, unthreaded message.
- "Send / send it" ("pošli", "odešli") → reply_send (or send_draft for an existing draft); works only when sending is enabled and the recipient is allowlisted, otherwise create the draft and say why.
- The first time the owner uses one of these words in a conversation, confirm in one sentence what you did and what the other two words would do. Ask when a request is ambiguous ("vyřiď to").
- reply_all=true when the owner says "reply to all" ("odpověz všem"). A signature configured on the setup page is appended by the server; do not add one yourself.
- Signature with a photo or logo: the owner ticks "signature from my mailbox" on the setup page, then either sends themselves an e-mail with the signature from their usual mail client and moves it into the folder "mailmcp-signature" (the newest message there is the signature, images are embedded), or pastes the signature to you and you call set_signature. get_signature shows what is in use. Nothing is stored in the token or on the server.

## 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), reply_draft and reply_send (threaded replies with the quoted original), get_signature and set_signature (signature kept in the mailbox folder "mailmcp-signature"), 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://maximailmcp.synology.me/setup.
- Login/authentication error when searching: wrong app password or 2-Step Verification not enabled; create a new app password and a new token.
- Google says "The setting you are looking for is not available for your account" on the app-passwords page: 2-Step Verification is off. Enable it first, then the app-passwords page works.
- "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 set but invalid, or the configuration exceeds the license; the page states the reason. Removing the variable runs the free tier (with the signature). Buy at https://maximailmcp.synology.me/pricing.
- "the free tier allows 2": the token has more mailboxes than the free tier allows on this server; remove mailboxes, or run your own server with a Personal licence (https://maximailmcp.synology.me/deploy).
- Editing a token: https://maximailmcp.synology.me/setup → "Edit an existing token" → paste token + edit password → Load → change → generate again → replace in the client.

## More

- Guided walkthrough (Czech/English): https://maximailmcp.synology.me/start
- Detailed guide (English and Czech): https://maximailmcp.synology.me/docs
- Full instructions for assistants: https://maximailmcp.synology.me/llms-full.txt
- Security and architecture audit (September 2026, internal, AI-assisted, published in full): https://maximailmcp.synology.me/audit
- For companies (one server, everyone with their own token, what IT asks, deployment with onboarding €990 including Unlimited): https://maximailmcp.synology.me/teams
- Security in detail (who sees what, when and where; the four rules; permissions table): https://maximailmcp.synology.me/security
- Privacy policy (what the server processes, nothing stored) and terms of service: https://maximailmcp.synology.me/privacy, https://maximailmcp.synology.me/terms
- Run your own server (one click on Vercel, Docker, Claude Desktop; needs MAILMCP_KEY + MAILMCP_LICENSE): https://maximailmcp.synology.me/deploy and https://github.com/kojott/mailmcp-dist
- Pricing (EUR): Free on mailmcp.ai (2 mailboxes for good, signature in composed messages), Personal €19 once (own server or Claude Desktop; one person, 5 mailboxes, no signature, own business included), Unlimited €149 once per server (a company, unlimited users), deployment with onboarding €990 (Unlimited included): https://maximailmcp.synology.me/pricing. Stripe is the merchant of record; keys are shown at https://mailmcp.ai/claim right after payment and e-mailed. Earlier €4.99 buyers owe nothing.
- Vendor: Swinging Dogs s.r.o., Jiří Dolejš, VAT ID CZ24825671. Deployment enquiries: https://jiridolejs.cz/mailmcp