alexneamtu/gmail-mcp

Search, read, and draft across personal and work Gmail accounts through one
self-hosted MCP endpoint. Choose which accounts to connect and whether to enable
sending and label changes. Only your configured Google identity can authorize
access.
Get started · Connect Claude · Connect Codex · Operations · CI
> [!NOTE]
> Early release for technically experienced self-hosters. Requires Node 24,
> Linux with systemd, an HTTPS hostname, and your own Google OAuth project.
> Each deployment supports one owner with multiple Gmail accounts.
## What you can do
| Capability | Tools | Access mode |
| Check connected aliases and local enrollment | listaccounts | Both |
| Search with Gmail queries and read messages | searchmessages, getmessage | Both |
| Read whole threads | getthread | Both |
| List and download attachments (up to 5 MB) | getmessage, getattachment | Both |
| Look up existing labels | listlabels | Both |
| Create plain-text drafts in the selected mailbox | createdraft | Both |
| Send an existing draft | senddraft | Full |
| Apply or remove existing labels | modifymessagelabels | Full |
Every tool takes an explicit account alias, such as personal or work.
Aliases refer to separately enrolled mailboxes. Forwarded addresses are read
through their destination mailbox; forwarding alone does not enable sending
from those addresses.
After connecting, try:
> Search work for unread messages from the past week and summarize the ones
> that need a reply.
> In personal, draft an email to friend@example.com suggesting lunch on Friday.
> Save it as a draft. Do not send it.
> [!IMPORTANT]
> Drafts mode omits the sending and label-modification tools. Google's
> gmail.compose scope still includes sending permission at the Google level.
> In full mode, the client must obtain your approval to send a specific draft;
> the server does not provide a separate human-approval screen for each send.
## How it works
mermaid
flowchart LR
client["Claude or Codex"] -->|HTTPS| tunnel["Cloudflare Tunnel"]
tunnel -->|Loopback HTTP| server["Gmail MCP · /mcp Owner-only OAuth + PKCE"]
server -->|"account: personal"| personal["Personal Gmail"]
server -->|"account: work"| work["Work Gmail"]
The server uses Streamable HTTP. Google authorization enrolls each mailbox;
a separate OAuth consent flow lets Claude or Codex use those enrolled accounts.
Credentials and authorization state live in encrypted SQLite storage on your
server. The service runs as a dedicated non-root user under systemd.
Email content is untrusted input. Message bodies are capped at 60,000 characters
(200,000 per thread) with explicit truncation indicators. Attachments are
capped at 5 MB; images return as image content, other files as embedded resources. Plain text is preferred; HTML-only messages
return labelled HTML text. See the security policy for the trust
boundaries, logging rules, and backup limitations.
## Setup
### Schema inspection for directories
Glama and other stdio inspectors can inspect the tool catalog without private
configuration or Google credentials:
sh
npm ci --ignore-scripts
npm run build
node dist/inspection-main.js
This entrypoint exposes the same nine tool definitions as full access mode. The