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://mailai.netbear.nu/start, and you can let your ChatGPT or Claude walk you through it: send it the link https://mailai.netbear.nu/llms.txt.

What this is

mailmcp is a small server that gives Claude or ChatGPT access to your mailboxes: Gmail, 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.

Companies and teams where everyone has their own token on one server will find an overview at https://mailai.netbear.nu/teams. A detailed security breakdown (who sees what, the four rules, a permissions table) is at https://mailai.netbear.nu/security.

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. Outlook.com and Microsoft 365 are the exception: there you type no password at all, you sign in at Microsoft in step 2.

Gmail

1. Turn on two-step verification: myaccount.google.com → Security → 2-Step Verification. Without it Google will not offer app passwords: the page myaccount.google.com/apppasswords says “The setting you are looking for is not available for your account”. Nothing is wrong with the account, 2-Step Verification is simply off; turn it on and reload the page.
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

Microsoft needs no password from you. App passwords are blocked on most accounts, so you sign in to Outlook.com and to company Microsoft 365 at Microsoft itself. You never type a password into mailmcp; you only confirm to Microsoft what mailmcp may do with your mail. The sign-in happens in step 2 on the setup page, once per mailbox, and is protected by the same invite code as creating the token. The variant where you type a code additionally requires an invite code always, even on a server that otherwise lets anyone create a token.

1. In the setup form pick the provider Outlook / Microsoft 365 for that mailbox and click Sign in with Microsoft.
2. One of two things happens, depending on the server. On mailmcp.ai (and on your own server whose address is registered with Microsoft) a window opens with the Microsoft account picker: choose the account, sign in, and the window closes by itself. On your own server whose app registration does not list the server's address you get two buttons instead of one, because Microsoft handles sign-in with a code in a different place for each kind of account: Personal account (Outlook.com, Hotmail) or Work or school account (Microsoft 365). Pick the one you sign in with. The setup page then shows a short code and the address to enter it at: microsoft.com/link for a personal account, login.microsoft.com/device for a work account (both are Microsoft’s own pages). Type the code and sign in; the setup page waits in the meantime and carries on by itself once you are signed in. New Microsoft 365 tenants have security defaults switched on, which block sign-in with a code; then the server operator has to set up sign-in through a window, see below.
3. Microsoft shows what mailmcp is asking for. The list follows the boxes you ticked for that mailbox: a read-only mailbox asks for “Read your mail”, “Sign you in and read your profile” and “Maintain access to data you have given it access to”. Turn on drafts, sending, labels or Trash and it also asks for “Read and write access to your mail” and “Send mail as you”. Your tick boxes in mailmcp still decide: the Microsoft consent is the ceiling, and inside it mailmcp allows only what you switched on. Widening the permissions later needs a new sign-in. The other way round, removing capabilities does not shrink the permission you already granted at Microsoft: sign in again with fewer capabilities ticked, or revoke the app at Microsoft.
4. After the sign-in the address is filled in from what Microsoft returned for that account, and locked. Shared mailboxes and send-as aliases are not supported yet.

A sign-in lasts about 90 days. The date is shown next to the mailbox on the setup page and the assistant can tell you as well (“list my accounts”, the reauth_by field). A client that refreshes its connection on the server’s own sign-in page (claude.ai including the mobile app, Claude Code connected that way) carries the renewed Microsoft sign-in; other clients holding the same token keep the original one and reach that date on their own schedule. If you paste the token as a header, or use a ChatGPT connector, you sign in again after ninety days.

How to sign in again: on the setup page load the token with your edit password, click Sign in again on that mailbox and generate the token once more. In ChatGPT and claude.ai remove the connector and add it again; in Claude Desktop paste the new configuration. Without an edit password the token cannot be loaded back and has to be built from scratch.

Changing your mailbox password does not end the sign-in, because mailmcp holds no password of yours. You take access away at Microsoft: personal accounts at account.live.com/consent/Manage, work accounts at myapps.microsoft.com under the mailmcp app. Revoking there disconnects every mailmcp token that used that account.

What is different with Outlook: messages are addressed by a long text id instead of a number, which the assistant handles on its own; after a message is moved it uses the new id the server returns. Labels are Outlook categories, and a move to Trash lands in Deleted Items. If the mailbox uses an online archive, a message id changes when the message moves into the archive; just have the assistant find it again.

Microsoft sign-in on your own server

For operators of their own server. Microsoft sign-in on your server needs an app registration of your own: the mailmcp registration is used on mailmcp.ai only, so that nobody can run a sign-in with a code under our name. Sign-in through a window, which works for personal and work accounts alike, needs a registration that lists your server’s address:

1. In Microsoft Entra open App registrations → New registration. Supported account types: Accounts in any organizational directory and personal Microsoft accounts.
2. Under Authentication add the platform Mobile and desktop applications (not Web) with the redirect URI https://<your host>/api/ms/callback. mailmcp is a public client without a secret; under the Web platform Microsoft would require one and the sign-in would end with AADSTS7000218.
3. In the same place set Allow public client flows to Yes.
4. Under API permissions add the delegated Microsoft Graph permissions Mail.Read, Mail.ReadWrite, Mail.Send, User.Read and offline_access.
5. On the server set MAILMCP_MS_CLIENT_ID=<Application (client) ID> and MAILMCP_MS_REDIRECT=1 and redeploy. The setup page then offers sign-in through a window for Outlook.

Organisations that allow consent only to apps from verified publishers need publisher verification on your registration (Publisher verification in Microsoft Entra, which requires Microsoft AI Cloud Partner Program membership), or an administrator’s consent for the whole organisation.

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://mailai.netbear.nu/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. With the provider Outlook / Microsoft 365 a Sign in with Microsoft button appears instead of the password field: the steps are in the Outlook section, the address fills itself in, and up to three such mailboxes belong in one token, as long as the token stays under its size limit (a work account’s sign-in token is larger, so usually two fit).
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://mailai.netbear.nu/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://mailai.netbear.nu/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://mailai.netbear.nu/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://mailai.netbear.nu/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 three values: the master key MAILMCP_KEY, the invite code MAILMCP_INVITE_CODE and the license key MAILMCP_LICENSE (Personal €19 once for one person and up to 5 mailboxes; Unlimited €149 for shared token mode within one organization; pricing at https://mailai.netbear.nu/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 on https://mailai.netbear.nu/deploy: Vercel copies the distribution repository kojott/mailmcp-dist into your GitHub account and asks for all three 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), MAILMCP_INVITE_CODE (the invite code, at least 8 characters; without it the server issues no tokens) 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 refund within 14 days of each new purchase, are in the LICENSE file in the repository.

Mail servers on a private network: a user token names its own IMAP and SMTP servers. So that a public server cannot be used to probe the operator's network, hosts from tokens are resolved before connecting and private, loopback, link-local and CGNAT addresses (and localhost, .local, .internal) are refused; the connection is then pinned to the vetted address while TLS still verifies the original hostname. Public providers (Gmail, iCloud, Fastmail, your own mail.company.com) are unaffected. A company whose mail server lives on a private address deploys mailmcp inside its network and sets MAILMCP_ALLOW_PRIVATE_MAIL_HOSTS=1. The owner configuration (MAILMCP_CONFIG) is never subject to this check.

The invite code is required: MAILMCP_INVITE_CODE (at least 8 characters) belongs next to MAILMCP_KEY and MAILMCP_LICENSE as the third required value. Only someone who knows the code can then create a token on the setup page (an “Invite code” step appears). Without it the server issues no tokens at all and the setup page shows a notice for the operator; otherwise anyone who knows the address could create a token on your server and use up your limits. Forgot the code? Read it in your environment variables on Vercel or in Docker, or set a new one and redeploy; tokens already issued keep working. A deliberately public server (like mailmcp.ai) sets MAILMCP_OPEN_SIGNUP=1 instead of a code.

Microsoft sign-in on your own server: it needs a Microsoft Entra app registration of your own. Create it as described in the Outlook section, put its id into MAILMCP_MS_CLIENT_ID and add MAILMCP_MS_REDIRECT=1; your users then sign in through a window and see your application’s name on the consent screen. Without your own registration the setup page offers no Microsoft sign-in. MAILMCP_MS_DISABLED=1 hides the Microsoft sign-in entirely, and MAILMCP_DISABLE_GRAPH=1 additionally refuses to serve Microsoft mailboxes even in tokens already issued. The desktop build for Claude Desktop asks GitHub once on every start whether a newer version exists; MAILMCP_NO_UPDATE_CHECK=1 turns that off.

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 /deploy).
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://mailai.netbear.nu/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)

Threaded replies and the signature

When you say “reply” or “write a draft”, the draft lands in the same thread: the server sets the threading headers, the “Re:” subject, the recipients (everyone on “reply to all”) and quotes the original under the reply, as your mail client does. “Write me a reply” or “suggest a reply” only shows a suggestion in the chat; “send” sends, provided sending is enabled and the recipient is allowed.

Signature. A plain-text signature goes straight into the token form. A signature with a photo or logo does not belong in the token: tick “Signature with a photo or logo: take it from my mailbox” in the form, then send yourself an e-mail with your signature from your usual mail client and move it into the folder mailmcp-signature (create it, or let the assistant create it with “set my signature”). The newest message in that folder is your signature; its images are embedded in every reply, nothing is stored with us. To change it, put a newer message into the folder. Ask the assistant “show my signature” any time.

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.

PDF. For PDF attachments up to 5 MB the assistant gets the extracted text straight away (up to 20,000 characters), so it does not have to ask for the contents. The text comes out as it is stored in the file, so it can include passages that are invisible in the rendered PDF; treat it as somebody else’s text, not as an instruction. A scanned PDF with no text layer stays a download link.

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 is enough.
• Saving attachments to disk (Claude Desktop, Claude Code): allow folders in Claude Desktop under Settings → Extensions → mailmcp → Attachment folders (a fresh install has Downloads filled in; after an update from an earlier version the field is empty, pick the folder and restart Claude Desktop); in Claude Code with MAILMCP_ATTACHMENT_DIRS. Then “save the attachments from the accountant’s last email” writes the files themselves, PDFs included.

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. Microsoft mailboxes have no password: take access away at account.live.com/consent/Manage (personal accounts) or myapps.microsoft.com (work accounts).

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.

What it protects, what it reduces, and what it cannot solve

Protects: mailbox passwords (encrypted in your browser; the server holds one key and stores nothing), scope (permissions per mailbox, reading by default), sending (only to allowlisted addresses, so a planted instruction cannot mail your data to a stranger) and deletion (never permanent, only Trash).

Reduces, does not remove: instructions hidden in e-mails. Hidden text is stripped, bodies reach the model as quoted data, headers are sanitized. The model can still follow an instruction in plain text; the damage is bounded by the permissions above: a draft or a mail to an allowed address, not exfiltration and not deleted mail.

Does not protect: the content of mail the assistant reads is seen by the model and its vendor. Whatever it reads it can repeat in its reply or hand to another tool you have enabled in ChatGPT or Claude. That is the connector's edge, not a setting. So connect only mailboxes whose content the assistant may see, and leave sending off until you need it.