Gmail MCP
Gmail MCP server: list, read, search and send email, manage drafts and labels.
Documentation
Gmail MCP is a free MCP server that gives your AI agent four Gmail tools and one admin tool, so you can ask it to list, read, search, and send email without leaving the editor. It is its own VS Code extension, it runs on your machine, and it talks to your own Google account.
There is no server to host and no config file to edit. You install the extension, sign in to Google once, and the Gmail tools appear in every agent it finds: VS Code Copilot, Claude Code, Cursor, OpenAI Codex, Google Gemini, Windsurf, Continue.dev, and Cline.
What you can ask
These work as ordinary requests once the extension is running:
- “Show me my last 10 emails”
- “Find emails from my manager this week”
- “Read the one about the invoice”
- “Draft a reply saying Thursday works”
- “Label everything from the hosting company as Billing”
- “Send the team a note about the release”
The four Gmail MCP tools
| Tool | What it does | What you can pass |
|---|---|---|
gmail_list | List recent emails with sender, recipient, subject, date, and a snippet | A result limit (20 by default), a search query, label IDs |
gmail_read | Read one email in full: headers, body text, and the list of attachments | The message ID |
gmail_search | Search using Gmail’s own query syntax | The query and a result limit |
gmail_send | Send an email from your account | To, subject, body, and optional CC and BCC |
gmail_search takes the same operators you type into the Gmail search box, such as from:, newer_than:7d, has:attachment, and is:unread. If a search works in Gmail, the agent can run it.
The Gmail admin tool
Everything that changes your mailbox, apart from sending, lives in one admin tool with named actions.
| Action | What it does |
|---|---|
create_draft, update_draft | Write a draft or change one |
delete_draft | Delete a draft (needs confirmation) |
add_label, remove_label | Put a label on a message or take it off |
create_label, delete_label | Create a label, or delete one (delete needs confirmation) |
trash, untrash | Move a message to the trash or back (trash needs confirmation) |
mark_read, mark_unread | Change the read status |
Trash and delete need explicit confirmation
Trashing a message, deleting a draft, and deleting a label only run with confirm: true. The agent is told this up front, so it has to ask you before it does any of them. Reading, searching, and labelling do not need it.
Three things people use it for
Morning triage
Ask for unread mail from the last day, have the agent read the ones that look urgent, and get a short summary of each. Two tools do the work: gmail_search with is:unread newer_than:1d, then gmail_read on the results.
Replies you review first
Ask for a draft instead of a send. create_draft leaves the message in your Drafts folder, where you can read it, change it, and send it yourself from Gmail.
Pulling facts out of a thread
When a bug report or a client request arrives by email, the agent can read the message and work on the code in the same session. You do not paste anything across.
Set it up in five steps
A setup wizard opens the first time you launch the extension. Most people pick OAuth, which works with a personal Google account and with a Google Workspace account.
- Create a project in the Google Cloud Console, or pick one you already have.
- Enable the Gmail API under APIs and Services.
- Create an OAuth client ID of type Desktop app.
- Paste the client ID and secret into the wizard.
- Sign in to Google in the browser window that opens, and authorize.
If your consent screen is set to External, add yourself as a test user first. Developers who already use the gcloud CLI can pick Application Default Credentials instead, and Workspace admins can use a service account key.
A service account needs domain-wide delegation before it can open a mailbox, so it only suits Workspace admins.
Using Gmail MCP with Claude Code, Cursor and other agents
You do not add a server entry by hand. The extension writes the registration for each agent it finds: ~/.claude.json for Claude Code, ~/.cursor/mcp.json for Cursor, ~/.codex/config.toml for OpenAI Codex, ~/.gemini/settings.json for Gemini, and the matching files for Windsurf, Continue.dev, and Cline. VS Code Copilot picks it up through the VS Code API.
Open a new session in any of them and the Gmail tools are in the tool list. If you only want some agents to have them, switch the others off in VS Code settings under gmailMcp.agents. The command “Gmail MCP: Remove from All Agents” takes every registration back out.
How it compares with Google’s own Gmail MCP server
Google now offers a remote Gmail MCP server as part of its Workspace MCP servers. It is in Developer Preview, so you need to join the Google Workspace Developer Preview Program and set it up through a Google Cloud project and the gcloud CLI.
| Gmail MCP (this extension) | Google’s Gmail MCP server | |
|---|---|---|
| Availability | Released, installs from the extension stores | Developer Preview |
| Where it runs | On your machine | Remote, hosted by Google |
| Send email | Yes, gmail_send | Drafts only (create_draft) |
| Read whole threads | One message at a time | Yes, get_thread |
| Trash messages | Yes, with confirmation | Not listed |
| Agent setup | Automatic for eight agents | You configure each MCP client |
Google’s list was read from its developer documentation on November 12, 2026, and a preview can change.
Limits
gmail_sendsends plain text. It does not send HTML or attach files.gmail_readlists attachments by name. It does not open them.- Lists and searches return 20 messages unless you ask for more.
Common questions
Is Gmail MCP free?
Yes. The extension is free and MIT licensed. Google does not charge for using the Gmail API.
Does it work with a personal Gmail account?
Yes. OAuth works with personal Gmail and with Google Workspace accounts.
Can the agent send email without asking me?
gmail_send is an ordinary tool call, so your agent’s own permission settings decide whether it asks first. If you would rather review every message, ask for a draft instead.
Does it cover other Google services?
No. Gmail MCP covers Gmail only. Each service has its own extension: Google Calendar MCP, Google Drive MCP, Google Docs MCP, Google Sheets MCP. Google Workspace MCP bundles all five.
Where does my email go?
Nowhere except Google. The MCP server runs on your own machine and calls the Google API with your credentials. There is no telemetry, and the sign-in token is kept in VS Code’s encrypted secret storage.
Use it without VS Code
Gmail MCP is also on npm, for Claude Code, Cursor, or any other MCP client. It needs Node.js 22 or newer.
npx -y @renzo.johnson/gmail-mcp
In Claude Code, one command adds it:
claude mcp add gmail-mcp -- npx -y @renzo.johnson/gmail-mcp
Outside VS Code there is no setup wizard, so the server takes your Google sign-in from the environment. It uses the first one it finds: an OAuth client ID, secret, and refresh token in GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET, and GOOGLE_OAUTH_REFRESH_TOKEN; a key file named in GOOGLE_APPLICATION_CREDENTIALS; or the gcloud CLI’s Application Default Credentials. The npm package page has the config block for Claude Code and Cursor.
Install it
Gmail MCP is free and MIT licensed. It is its own extension, with only the Gmail tools. If you want Gmail, Calendar, Drive, Docs, and Sheets in one install, use Google Workspace MCP instead. Install one or the other, because both register the same Gmail tools.
- Install Gmail MCP from the VS Code Marketplace
- Install Gmail MCP from Open VSX for VSCodium, Cursor, and Windsurf
- Run Gmail MCP from npm with npx, in any MCP client
Listed in the official MCP Registry as com.renzojohnson/gmail-mcp.
Related
- Google Workspace MCP, all five Google services in one extension
- Google Drive MCP, Google Calendar MCP, Google Sheets MCP, and Google Docs MCP, the other service pages
- All Google MCP servers, the full list of 20