mailmcp is a self-hosted MCP server that provides email access capabilities for ChatGPT, Claude, and other MCP clients. It works based on IMAP and SMTP, can connect to multiple mailboxes simultaneously, supports any provider, and supports two-way attachments. This repository is a prebuilt distribution (compressed bundles under dist/, no build step required), uses a commercial license, can run as a free version without a key, and the source code is not provided.
Purpose and positioning: suitable for scenarios where you have multiple mailboxes, use providers without official connectors, or need to handle attachments. According to official statements, as of September 2026, the official Gmail and Outlook connectors in ChatGPT and Claude can each only handle one mailbox and cannot send attachments. With mailmcp, you can ask questions and get answers across Gmail, iCloud, and corporate email servers in a unified way, for example obtaining invoice download links from billing emails with a reply already drafted.
Main capabilities: each tool is controlled by the permissions in the token and per mailbox. It supports reading, threaded replies, drafts, sending with a sender allowlist, and sending and receiving attachments. Each mailbox also has a protection level for verification emails (Off, Basic, Standard, Strict, Custom; new mailboxes default to Standard): hidden emails will not appear in any answers, and Standard and above will remove verification codes and login links from other emails. This mechanism can intercept typical verification emails, but not all possible cases. In apps that support MCP Apps, the triage, digest, draft tools, and bulk_preview also display clickable panels; panels can be disabled per token on the settings page (or via the stdio setting MAILMCP_UI=off). All tools are listed to the client; calls not allowed by the token will fail and indicate the missing permission.
How to use: requires Node 22 (or Vercel, or Docker), an HTTPS address (ChatGPT and Claude connect only via HTTPS), and an app-specific password for each mailbox. Gmail requires two-step verification to be enabled first, otherwise Google will hide the app-specific password page (organizational policies or Advanced Protection may also hide it). Outlook.com and Microsoft 365 require no password: users log in to Microsof on the settings paget. An invite code (MAILMCP_INVITE_CODE, at least 8 characters) must be set, otherwise the server will not issue tokens; a server intended to be public can set MAILMCP_OPEN_SIGNUP=1. Deployment can be done via the Vercel button, or by running Docker yourself (docker build -t mailmcp . && docker run -d -p 8080:8080 ...), or by directly running node dist/node.js. After deployment, open https://<your-server>/start and follow the instructions to choose a provider, paste the email and app-specific password, and check the actions the assistant may perform (reading is enabled by default, drafts are a good second step, sending is limited to whitelisted recipients). The page encrypts the password in the browser and issues a token. How to connect: ChatGPT → Settings → Apps → Create → URL https://<your-server>/mcp; claude.ai → Settings → Connectors → Add custom connector, and sign in with the token. You can also try it without deploying by using the shared server mailmcp.ai/setup, but the shared server operator can technically see your configuration during service requests. Claude Desktop can download mailmcp.mcpb and open it on the desktop, then paste the configuration from /setup → "Values for your own deployment". Behind a reverse proxy, set MAILMCP_PUBLIC_URL or MAILMCP_TRUST_PROXY=1; for company mail servers using private addresses, set MAILMCP_ALLOW_PRIVATE_MAIL_HOSTS=1; changing MAILMCP_KEY invalidates all tokens.
Outlook and Microsoft 365 support: these mailboxes do not have passwords, and Microsoft rejects password sign-in on most accounts. In /setup, users choose Outlook / Microsoft 365 and click Sign in with Microsoft. This requires your own Entra app registration (MAILMCP_MS_CLIENT_ID); without it, the setup page does not offer Microsoft sign-in. When the server origin is a registered redirect URI (MAILMCP_MS_REDIRECT=1), the button opens a popup with an account selector; otherwise the page asks the user whether to use a personal account or a work/school account, and displays a short code to enter at microsoft.com/link or login.microsoft.com/device. Sign-in is behind the invite code (the device code relay requires an invite code even when MAILMCP_OPEN_SIGNUP=1), and the user sees your app's name on the consent screen. Tokens do not reach the provider: sign-in runs on your server. Each token supports up to three Outlook mailboxes; the consented Microsoft permissions follow the checked capabilities (read-only is Mail.Read, otherwise Mail.ReadWrite and Mail.Send), and expanding permissions later requires signing in again; sign-in lasts about 90 days (the date is shown in /setup and in reauth_by from list_accounts, and clients refreshed through official OAuth rotate automatically); changing the mailbox password does not terminate sign-in, while revoking the app in Microsoft terminates all tokens using that account. Tenants that leave consent to administrators require one-time approval. Mail is transported through Microsoft Graph, so message ids are strings rather than numbers, and labels are Outlook categories.
Steps to bring your own Microsoft app registration: Microsoft Entra → App registrations → New registration; for supported account types, choose "Accounts in any organizational directory and personal Microsoft accounts"; Authentication → add platform "Mobile and desktop applications" (not Web), with redirect URI https://<your host>/api/ms/callback (mailmcp is a public client without a secret, and the Web platform would require a secret and cause the AADSTS7000218 error); Authentication → set Allow public client flows to Yes; API permissions → delegated Microsoft Graph Mail.Read, Mail.ReadWrite, Mail.Send, User.Read, offline_access; setSet MAILMCP_MS_CLIENT_ID and MAILMCP_MS_REDIRECT=1, then redeploy.
Security and data flow: The settings page encrypts the mailbox password in the browser into a split-key token. The server holds one master key, decrypts the configuration only when servicing a request, keeps it in memory for at most 15 minutes after the last request, has no database, and does not keep copies of emails. What leaves the server is: IMAP/SMTP traffic to the mail provider and tool results for the assistant (the AI vendor sees the result of each tool call, but never sees the password). License validation is performed offline. The only requests to the vendor are a daily update check and the usage statistics described below; the purchase button links to the vendor. Email bodies are marked as untrusted data, hidden text is removed, and header fields are sanitized to reduce the risk of instructions embedded in emails; however, the model cannot be made immune. The protocol uses OAuth 2.1 with PKCE, dynamic client registration and client metadata documents, encrypted tokens with replay protection, and login rate limiting. Read-only by default, send allowlist, no permanent deletion. Revocation: delete the app-specific password at the provider and the token becomes invalid; Outlook mailboxes hold a Microsoft refresh token rather than a password, and the app can be revoked at account.live.com/consent/Manage or in My Apps for work accounts. Rotating MAILMCP_KEY invalidates all tokens on the server.
Usage statistics: Each copy asks mailmcp.ai at most once per day whether there is a new version; Claude Desktop asks on every startup. Server copies (Vercel production, Docker, Node), unless disabled, also send usage statistics in that request; Claude Desktop and other desktop (stdio) copies send only when enabled, and at most once per day regardless of how many times they start. The request body contains: s for schema, v for the major.minor version number, r for runtime (vercel, docker, node, claude-desktop, or stdio), d for a number that remains constant within one calendar month, computed from a value that never leaves the server (the Vercel project id, otherwise a machine id, or a random salt written once per copy to ~/.mailmcp/stats-salt, mixed with it when MAILMCP_KEY is set). No license key, conaddress, email, or content. mailmcp.ai only keeps daily and monthly counts per version and runtime, and it is impossible to tell from them which installation sent a request. The host Vercel logs the IP address of every request for 1 day, like any website; the code itself never stores that address. Vercel preview deployments only send update checks; CI runs and builds from source send nothing. Each copy logs one line at startup stating whether statistics are ON or OFF. To turn it off (1, true, yes, or on): MAILMCP_NO_STATS=1 or MAILMCP_STATS=0 (turns off statistics, keeps update checks), MAILMCP_NO_UPDATE_CHECK=1 (sends no requests at all), DO_NOT_TRACK=1 (turns off statistics). In Claude Desktop, the corresponding extension settings are "Anonymous usage statistics" (off by default) and "Check for updates".
License and support: The license agreement is in LICENSE (English translation first, the Czech original is authoritative): one key corresponds to one running installation, no redistribution, no serving other people's email addresses, and no running mailmcp as a hosted service. All 0.x updates are included; the 1.0 upgrade may be paid, and 0.x remains usable. 14-day no-questions-asked refund. Company deployment 990 euros: two hours of online onboarding support, deployment on your Vercel or cloud, includes an Unlimited license.
Limitations: The source code is not provided; ChatGPT and Claude connect only via HTTPS; Gmail requires two-factor authentication and an app-specific password; Outlook/Microsoft 365 requires registering your own Entra app; a maximum of three Outlook mailboxes per token; attachment links are valid for one hour and carry an encrypted token, during which anyone holding the link can use it; the operator of a shared server can technically see the configuration during service requests; prompt injection protection cannot make the model immune.
