oauth-mail-mcp
Provides OAuth-based access to a single Gmail mailbox over IMAP/SMTP, enabling listing mailboxes, listing and searching messages, reading bodies and attachments, managing flags, creating drafts, and optionally sending mail. Authorization runs through a browser-approved OAuth grant (using Thunderbird's public client, so no Google Cloud app registration) with tools to start and resume the flow, and tokens are persisted and refreshed automatically.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
oauth-mail-mcp
OAuth-only mail access for one mailbox per container, exposed as a remote MCP server.
Gmail and Microsoft 365 both killed password auth for mail clients, so an agent that wants real mailbox access needs a browser-approved OAuth grant that survives restarts. Doing that usually means registering your own Google Cloud or Entra application — which for a work tenant means an admin request, and for Gmail in "Testing" status means a refresh token that dies every seven days.
This project takes a different route: it reuses the public OAuth clients Mozilla ships in Thunderbird, so the consent screen reads "Thunderbird", no application registration exists on either side, and the refresh token is long-lived. himalaya does the IMAP/SMTP work, ortie owns the OAuth grant and refreshes it on read, and this server exposes the result over MCP — one container, one account, one bearer token.
Why not an existing project
Project | Gap |
| Closest by capability (OAuth2, IMAP/SMTP/Graph/EWS). No published image, unauthenticated HTTP transport, no health endpoint, refresh tokens must be provisioned by hand |
| Requires your own Azure app registration and Google Cloud OAuth client — the admin approval this project avoids |
| Published image, but password/app-password auth only; Exchange Online rejects basic auth |
| IMAP passwords only, so Microsoft 365 cannot connect |
Google Workspace / Microsoft 365 official MCP servers | Developer preview or tenant-admin provisioning, own Cloud project, 7-day tokens in Testing |
None of them combine an unauthenticated-free HTTP MCP surface, a health signal, in-container OAuth and no app registration. That combination is what this repo is.
Related MCP server: imap-mcp
Quick start
cp .env.example .env # fill MAIL_ADDRESS, MAIL_MCP_TOKEN, GOOGLE_CLIENT_SECRET
docker compose up -d
curl http://localhost:18080/healthFirst run reports unauthenticated — no token exists yet. Authorise through an MCP client
by calling mail_authorize_start, or run ortie inside the container:
docker exec -it oauth-mail-mcp-gmail sh -lc 'ORTIE_CONFIG=/data/config/ortie.toml ortie auth get -a gmail'Environment
Variable | Required | Meaning |
| yes |
|
| yes | mailbox address, used as the SASL username and |
| yes | bearer token the MCP client must present ( |
| no | default |
| no |
|
| gmail | Mozilla's public Thunderbird client secret |
| no | health probe cache, default 60 |
| no | body truncation for |
Tools
mail_status, mail_mailboxes, mail_list, mail_search, mail_read, mail_attachment,
mail_flags, mail_draft, mail_send, mail_authorize_start, mail_authorize_resume.
No delete, no move, no folder creation. The default is read-only: with MAIL_READ_ONLY=true
(absent any setting) mail_flags, mail_draft and mail_send all refuse, so an injected mail
body can only cause reads. To write, set MAIL_READ_ONLY=false; to send, also
MAIL_ALLOW_SEND=true. Reading never marks a message as seen (himalaya peeks).
Authorising by hand
The container can run its own OAuth flow, so reauthorising never needs the agent or a host shell:
# start a grant: prints a Google URL, or a Microsoft device code
docker exec -it oauth-mail-mcp-gmail mail auth-start
# finish it: pass the redirected URL (Gmail), or nothing for Microsoft (it waits for approval)
docker exec -it oauth-mail-mcp-gmail mail auth-resume '<redirect url>'
docker exec -it oauth-mail-mcp-m365 mail auth-resume
# check state at any time
docker exec -it oauth-mail-mcp-gmail mail statusOAuth flows
Gmail — authorisation code with a loopback redirect. mail_authorize_start returns a
Google URL. Approve it on the machine where http://localhost:18081 reaches this container
(the Mac); the callback listens on 8082, published only on loopback, and writes the token.
From a phone or another computer, the redirect dies on that device — paste the address-bar
URL into mail_authorize_resume and the exchange completes server-side. Google offers no
device-code flow for the Thunderbird client (invalid_client: Invalid client type), which
is why the paste path exists.
Microsoft 365 — device code. mail_authorize_start returns a code and
https://login.microsoft.com/device. Type it on any device; the container polls and stores
the token. No callback, no LAN dependency, no paste.
Health
GET /health (port 8081, published to the LAN for Uptime Kuma):
Status | HTTP | Meaning |
| 200 | token resolved and IMAP answered |
| 503 | no token granted yet |
| 503 | grant revoked, expired or rejected |
| 503 | token fine, provider unreachable |
| 503 | first probe not finished |
Probes are cached 60 s. The container has a HEALTHCHECK on the same endpoint but no
auto-restart: restarting cannot fix a dead grant, and a crash loop would hide the red state
that monitoring is supposed to show.
Kuma: HTTP keyword monitor on http://<host>:18080/health, keyword "status":"ok".
Security
Refresh tokens live only in the container's
/datavolume, mode 0600. No tool returns them./mcprequires the bearer token and is not published to the LAN — only/healthis.Config files are rendered at start from environment variables and contain no secrets.
All himalaya/ortie invocations are serialised with a file lock, because Microsoft rotates refresh tokens on use and two concurrent refreshes would invalidate each other.
Build
GitHub Actions builds multi-arch images to ghcr.io/jmengit/oauth-mail-mcp, tagged
latest, sha-<short>, and YYYY.MM.DD-<short>. Pin the dated tag in production so
rollback is a tag change. upstream.yml checks daily for new himalaya/ortie releases and
opens a PR bumping versions.env.
Licence
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Hosted MCP server for your Gmail, Outlook and IMAP mail, with mailboxes and scopes set per agent.
Your agent needs a mailbox of its own — to receive, thread, draft and send, with attachments, without borrowing your personal inbox or your company's SMTP. **What you can ask for** • "Create an inbox for this agent and tell me its address." • "Read the new messages in this thread and draft a reply." • "Send this message with the attachment and wait for the response." • "Search this inbox for everything from that domain." • "Show delivery metrics and the events on this inbox." **How to use it** Point any MCP client at https://mcp.aisa.one/mail/mcp and sign in with OAuth — there is no key to create or paste. 49 tools: create and delete inboxes, list and read messages, raw message bodies, attachments, threads, drafts and draft attachments, send and reply, message search, inbox events, metrics, and list entries — reads and writes. **Why this rather than the source** A real inbox an agent owns, rather than an SMTP credential it borrows from a human. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Find the contact elsewhere in the catalogue, then write to them from here — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/sales/mcp finds the person to write to.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables MCP clients to read, search, send, reply, and organize Gmail messages across multiple accounts via OAuth, with real MIME attachments and live signatures.23Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to check, list, search, read, send, draft, and trash email in a single IMAP mailbox using standard IMAP and SMTP settings, with sending and trash moves enabled only when explicitly allowed.36 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables an MCP client to read, draft, organize, send, and delete email across multiple Gmail and Exchange Online/Outlook.com accounts, with per-account capability policies, recipient allowlists, confirmations, minimum OAuth scopes, and local audit logging.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to access a personal Outlook.com mailbox and calendar through Microsoft Graph, supporting email search, reading, drafting, sending, organization, and calendar event management.89 npmMIT