gmail-mcp — Claude Code MCP server: what it does, how to install
Connects Gmail accounts to your AI assistant using a personal Cloudflare Worker. It reads, sends, and handles message threads across multiple mailboxes.
Open on GitHubWhat gmail-mcp does
The server deploys as a remote endpoint on your own Cloudflare Worker. It searches emails, sends new messages, forwards threads, and handles reply-all with quoted history. Attachments and inline images load directly. It also respects original character encodings without corrupting non-UTF-8 parts.
Each configured connection ties strictly to a single Google mailbox. Because of that design, an assistant cannot hit an unintended inbox through bad argument values. Refresh tokens remain inside your own OAUTH_KV namespace. Mailbox settings like filters or vacation notices remain untouched because the server omits the gmail.settings scope entirely.
What it helps with
- send messages and reply-all with quoted history inside Claude Code
- manage several Google mailboxes without running a local background process
- read emails with non-UTF-8 charsets and extract attachments correctly
- access your email assistant securely from a laptop, browser, or mobile device
Example prompts for the agent
- Find unread invoices from last week and summarize the total amounts.
- Reply to all recipients on the deployment thread and confirm the release time.
- Forward the latest message from Alice to the team and label it as
Reviewed.
How to install gmail-mcp
Install
The MCP registry has no launch command for it: see the repository README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about gmail-mcp
How do you deploy gmail-mcp?
You need a Cloudflare account, Google Cloud credentials, and bun. Clone the repository via git clone https://github.com/mkpoli/gmail-mcp && cd gmail-mcp, install dependencies with bun install, and execute bun run setup.
How does gmail-mcp differ from built-in assistant connectors?
Default vendor connectors cannot send outbound messages and link to only one mailbox. gmail-mcp can send mail, preserves attachments, and connects several mailboxes at once.
Why does the Google OAuth app need to be published?
Google revokes refresh tokens after 7 days if the OAuth consent screen stays in Testing status. Publishing the app avoids weekly disconnects and supports up to 100 accounts.
