Connect your mail to Claude or ChatGPT. Step by step.

From your first app password to your first question, “what came in from accounting this week”. Shared server: 10 minutes. Your own server for a company: another 15. In a hurry? A short version with a Czech/English switch is at https://mailmcp.ai/start, and you can let your ChatGPT or Claude walk you through it: send it the link https://mailmcp.ai/llms.txt.

What this is

mailmcp is a small server that gives Claude or ChatGPT access to your mailboxes: Gmail, Outlook, iCloud, Fastmail, Yahoo, Zoho or any IMAP account, several at once if you like. Claude can then search, read, summarise and prepare replies as drafts. Sending, moving and deleting are switched off until you turn them on yourself.

The crucial difference from off-the-shelf connectors: your mail passwords never travel through OpenAI or Anthropic in readable form and the server never stores them. Your whole configuration travels inside a single encrypted token. The key to it is split in two halves: one is in the token, the other (the master key) lives only on the server. Anyone holding just the token (logs at OpenAI, for example) can read nothing. Anyone holding just the master key has no configuration. Only the server can decrypt, and only at the moment it is handling a request for you.

Which path to take

Steps 1 to 3 describe the shared server. Your own server and the local variants come later.

Step 1 · Passwords for your accounts

mailmcp signs in to mailboxes over IMAP/SMTP, exactly like the mail app on your phone. Most providers require an app password for that: a special password you generate and can revoke at any time without changing your main password. Prepare one now for every mailbox.

Gmail

1. Turn on two-step verification: myaccount.google.com → Security → 2-Step Verification. Without it Google will not offer app passwords.
2. Open myaccount.google.com/apppasswords, enter mailmcp as the name and click Create.
3. Google shows 16 characters in four groups. Copy them (the spaces do not matter). You will see this password only once.

Outlook / Microsoft 365

App passwords work only if your tenant administrator enables them (they are blocked by Security defaults and by most MFA policies). Without an app password, signing in with a password usually fails, because Microsoft requires OAuth. OAuth support in mailmcp is planned.

iCloud

1. account.apple.com → Sign-In and Security → App-Specific Passwords → Generate.
2. In the setup form enter the full address (for example name@icloud.com); mailmcp works out the difference between the IMAP and SMTP logins on its own.

Fastmail, Yahoo, Zoho

All three require an app password from the account security settings (Fastmail: Settings → Privacy & Security → Integrations). Fastmail does not offer IMAP access on the Basic plan.

Your own domain, company server

Have ready the IMAP server address and port (usually 993), the SMTP server address and port (465 or 587), the login name and the password. You will find them in your hosting provider's instructions under “mail client settings”.

Step 2 · Creating your token

Open https://mailmcp.ai/setup. The page runs in your browser: the passwords you type into it are encrypted before anything leaves your computer. Only a 32-byte encryption key goes to the server, which seals it with its master key and hands it back. Nothing is stored.

1. Accounts. For every mailbox pick the provider, enter a short Account id (for example personal, work; the assistant will use it in its answers), the e-mail address and the password from step 1. For your own server fill in the IMAP/SMTP details as well.
2. Permissions. Tick what the assistant may do with that mailbox. A good starting point: Read & search and Create drafts. Turn sending on only together with an allowlist (for example @yourcompany.com), otherwise the assistant cannot send anything at all.
3. Edit password. Choose a password you will use later to load the token back, when you want to add a mailbox or change permissions. Assistants never see it, so a token on its own can never hand over your mail passwords. Without it the token can later only be created again from scratch.
4. Click Generate my token. Copy Your mailmcp token (the long text starting with mmt1.). Save it in your password manager: whoever holds it can read your mail through this server.

Step 3 · Connecting clients

The server address is https://mailmcp.ai/mcp. The token is used in two ways: as a bearer token where the client can send headers, or pasted into the login page where the client uses OAuth.

ChatGPT

1. Settings → Connectors (or Apps & Connectors) → in the advanced settings turn on Developer mode. Custom connectors are available on the Plus, Pro, Business, Enterprise and Edu plans.
2. Create → name “mailmcp”, URL https://mailmcp.ai/mcp.
3. Authentication: either OAuth (ChatGPT opens the server's login page, where you paste your token), or, if the form offers a bearer token, paste the token straight in. Do not add any other headers or variables.
4. Enable the connector in the chat and try: “List my mail accounts.”

claude.ai (web, mobile, Claude Desktop)

1. Settings → Connectors → Add custom connector, URL https://mailmcp.ai/mcp, save, Connect.
2. The server's login page opens. Paste your token and confirm. The connector is then active in the mobile app as well. Requires the Pro plan or higher.

Claude Code

claude mcp add --transport http mailmcp https://mailmcp.ai/mcp \
  --header "Authorization: Bearer mmt1.…your whole token…"

Cursor, VS Code, Gemini CLI and others

Same address, the token either as a bearer header or through OAuth sign-in. The exact snippets are in the details for individual clients.

Your own shared server

If you want to run the server for yourself or for a team, you need two values: the master key MAILMCP_KEY and the license key MAILMCP_LICENSE (Personal €4.99 for one person and up to 5 mailboxes; Unlimited €129 for shared token mode; pricing at https://mailmcp.ai/pricing). The server stores nothing, so it needs no database; for personal use the free Hobby plan on Vercel is enough, for a company use Vercel Pro or Docker.

1. Accounts at github.com and vercel.com.
2. Click the Deploy button in the wizard at https://mailmcp.ai/start: Vercel copies the distribution repository kojott/mailmcp-dist into your GitHub account and asks for both variables right away. (Manually: fork the repository and in Vercel choose Add New → Project → Import.)
3. Under Environment Variables add MAILMCP_LICENSE (the key from the e-mail you got after buying) and MAILMCP_KEY: 32 random bytes in base64url. Generate them in a terminal with node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))", or on the setup page in the section for your own deployment (the MAILMCP_KEY field). Save the key in your password manager: losing it invalidates every user token.
4. Deploy. At https://your-project.vercel.app you will see the home page in shared mode; users create their tokens at /setup.

Licensing: one license = one running installation; you can move it to another server at any time. The terms, including the 60-day refund, are in the LICENSE file in the repository.

Closed sign-up: set the extra variable MAILMCP_INVITE_CODE. Only someone who knows the code can then create tokens on the setup page (an “Invite code” field appears). Without it, anyone who knows the address can create a token on your server and use up your limits.

Your own reverse proxy (Docker, VPS): set MAILMCP_PUBLIC_URL to the public address of the server. Without it the server does not trust X-Forwarded-* headers (on Vercel it trusts them automatically).

Optionally you can also add MAILMCP_CONFIG with the operator's own mailboxes to your server; it then works as a single-user server (connector password, your own bearer token) and a shared one at the same time.

My computer only · A · Claude Desktop

For the local variants you need the values MAILMCP_CONFIG and MAILMCP_KEY from the “Values for your own deployment” section of the setup page, not a token.

1. Download mailmcp.mcpb from the latest release on GitHub.
2. Double-click it (or in Claude Desktop: Settings → Extensions → Install Extension). You need Node.js 20 or newer installed; Claude Desktop will tell you if it is missing.
3. Paste MAILMCP_CONFIG and MAILMCP_KEY into the form. They are stored in your computer's system keychain.
4. Open a new chat and write: “List my mail accounts.” Claude should call the list_accounts tool.

B · Your own single-user server on Vercel

An alternative to the shared server for anyone who wants everything in their own account but does not want to install anything. The procedure is the same as for your own shared server, except that instead of a master key you set two variables holding your configuration.

1. Create an account at github.com and at vercel.com (sign in with GitHub, it saves a few steps).
2. Make your own copy of the distribution repository on GitHub: on github.com/kojott/mailmcp-dist click Fork (or use the Deploy button at /start).
3. In Vercel: Add New → Project → Import and pick your mailmcp fork. Vercel detects the app on its own; change nothing.
4. Before clicking Deploy, expand Environment Variables and add MAILMCP_CONFIG and MAILMCP_KEY from step 2. (If you forget, you can add them later under Settings → Environment Variables and then pick Redeploy on the Deployments tab.)
5. Click Deploy. In a minute you get an address like https://mailmcp-xyz.vercel.app. Open it: you should see the home page with your mailboxes. The /health address returns {"ok":true}.
6. In claude.ai: Settings → Connectors → Add custom connector. As the URL enter your address with /mcp at the end, for example https://mailmcp-xyz.vercel.app/mcp. Save and click Connect.
7. Your server's login page opens. Enter the connector password from the setup (not your e-mail password). Once confirmed, the connector is active in the mobile app and in Claude Desktop too.

C · Claude Code locally

Against the shared server the command from step 3 is all you need. Locally, with no hosting (requires Node.js 22+):

claude mcp add mailmcp -e MAILMCP_CONFIG="mmc1..." -e MAILMCP_KEY="..." -- npx -y mailmcp

To verify: claude mcp list shows mailmcp as connected.

Details for ChatGPT, Cursor, VS Code, Gemini CLI and others

Every tool connects to an address ending in /mcp. Two ways to sign in: OAuth (the client opens the server's login page, where you paste your token) or a bearer token in a header, where you paste the same token. The examples below use the address of your own server; on the shared server substitute https://mailmcp.ai/mcp.

ChatGPT

1. In ChatGPT open Settings → Connectors (in some versions Settings → Apps & Connectors) and turn on Developer mode in the advanced settings. Custom connectors are available on the Plus, Pro, Business, Enterprise and Edu plans.
2. Click Create (or +), enter the name “mailmcp” and as the URL your address with /mcp, for example https://mailmcp-xyz.vercel.app/mcp. Leave the authentication set to OAuth.
3. ChatGPT redirects you to the server's login page. Paste your token (on your own single-user server, the connector password).
4. Enable the connector in the tools menu of the chat. ChatGPT uses the search and fetch tools, which mailmcp provides for it: “search” searches all mailboxes with one query (Gmail syntax works for Gmail accounts, and you can pick a single mailbox with the prefix account:work), “fetch” reads one specific message. In Developer mode ChatGPT also has all the other tools available, drafts included.

Cursor

The file ~/.cursor/mcp.json (globally) or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "mailmcp": {
      "url": "https://mailmcp-xyz.vercel.app/mcp",
      "headers": { "Authorization": "Bearer mmt1.…your whole token…" }
    }
  }
}

Without the headers entry Cursor starts an OAuth sign-in in the browser; both variants work.

VS Code (GitHub Copilot)

The MCP: Add Server command → HTTP → address https://mailmcp-xyz.vercel.app/mcp. On the first connection VS Code opens the browser to sign in (OAuth). Written by hand into mcp.json:

{
  "servers": {
    "mailmcp": {
      "type": "http",
      "url": "https://mailmcp-xyz.vercel.app/mcp"
    }
  }
}

Gemini CLI

gemini mcp add --transport http --header "Authorization: Bearer mmt1.…your whole token…" \
  mailmcp https://mailmcp-xyz.vercel.app/mcp

Or in ~/.gemini/settings.json as "mailmcp": { "httpUrl": "https://…/mcp", "headers": { "Authorization": "Bearer …" } }.

Windsurf, Zed, Continue, JetBrains and others

Anywhere you can enter a “remote MCP server” with a Streamable HTTP address and an Authorization: Bearer … header, the same snippet as for Cursor works. Clients that speak OAuth sign in with the connector password.

How to work with it

Talk to Claude normally; it picks the tools itself. Questions that work well:

• “List my mail accounts and what you are allowed to do with them.”
• “What came in over the last three days across all accounts? Group it by account and tell me what needs a reply.”
• “Find invoices with an attachment from this month in my work account.” (Gmail also understands queries like from:accounting has:attachment newer_than:30d.)
• “Read me the last message from Chris Miller and prepare a polite reply as a draft.” You will find the draft in the Drafts folder of your mail app and send it yourself.
• “Mark all newsletters from this week as read.” (works only with the Flag / label / move permission enabled)

Attachments

Attachments do not load up the assistant's context. For every message the assistant gets a list of attachments and, for each one, a download link valid for one hour. You click it and the file downloads straight from the server (which fetches it from your mailbox at that moment) without ever passing through OpenAI or Anthropic. Text attachments (TXT, CSV, JSON, XML) can also be read by the assistant directly; the contents of any other file go into the context only when you explicitly ask (“load the contents of that attachment for me”, up to 2 MB). The link works for anyone who has it, for an hour, so pass it on as carefully as a password.

Limits you set during setup: the length of a message body per read (8,000 characters by default), how many messages may be sent per hour, and whether attachments are listed only or downloadable too.

Sending attachments

The assistant can send an attachment as well, and the file never goes through the chat. Three ways:

• An attachment already in your mail: “Forward that invoice to accounting.” The assistant uses forward_message, or attaches one specific attachment to a draft or an outgoing message; the server takes it straight from the mailbox.
• A file the assistant wrote: a contract, a CSV, a quote. The assistant hands it over with upload_attachment and attaches it.
• A file from your disk: the assistant asks for a one-hour upload link (request_upload). Claude Code, Cursor or Gemini CLI can send the file themselves (curl -T file link); in ChatGPT or claude.ai you open the link and drop the file in. In Claude Desktop the path to a file in an allowed folder (attachment_dirs) is enough.

Uploaded files wait in the mailmcp-uploads folder of your mailbox (the server keeps nothing) and are deleted once attached. The limit is 20 MB per message; on Vercel an upload through a link handles roughly 4 MB per file, so send larger files by forwarding them from your mail, or run mailmcp in Docker.

Changing your configuration

Shared server: at the bottom of the setup page expand “Edit an existing configuration”, paste your current token and your edit password and click Load. The form fills itself in (the passwords are decrypted only in your browser). Add a mailbox or change permissions, click Generate my token again and put the new token into your clients in place of the old one (for ChatGPT and claude.ai: disconnect and connect again). The old token stops working as soon as you delete the app password it contains at your provider.

Your own single-user server: Settings → Environment Variables → edit MAILMCP_CONFIG → Deployments → Redeploy. Claude Desktop: Settings → Extensions → mailmcp → Configure.

To revoke access at any time: delete the app password at your provider (Google, Microsoft, Apple…). The server then cannot get into the mailbox, no matter who holds the token.

Troubleshooting

Security in five sentences

The server has been through a security audit (cryptography, OAuth, the mail layer, the web, operations). The known limitations of the stateless design, which the audit confirmed: the protection against replaying an authorization code holds within a single instance (the code is valid for 3 minutes and is protected by PKCE), access tokens are valid for 30 days (because of ChatGPT, which does not refresh them itself) and cannot be revoked individually before they expire (refresh tokens last 90 days); the only immediate revocation is deleting the app password at your provider, sign-in attempt limits are counted per server instance, and attachment links are valid for an hour for anyone holding them.

• E-mail is untrusted content: the server strips hidden text and marks message bodies as data, so that a forged e-mail cannot “instruct” Claude. Even so: check whatever Claude proposes to send.
• Start with read-only and drafts. Turn sending on only with a narrow allowlist.
• Keep your token in a password manager, like a password. Whoever holds it can read your mail through this server; without the server's master key, though, it is unreadable for anyone else (OpenAI and Anthropic included). A token on its own never hands over your mail passwords: loading it back into the form also requires the edit password, which assistants never see.
• Use app passwords, not your main account password. They can be revoked at any time with one click.
• Signing in to the connector is limited to 5 attempts per 15 minutes; access tokens are valid for 30 days and refresh automatically.