Verified MCP server: Gmail
The tool list below is a live capture from the running server; an authenticated tool call is still pending credentials.
The short answer
Last verified 2026-08-03
The Gmail MCP server hands an AI assistant a set of Gmail actions: search the inbox, read a message, send or draft mail, move things between labels, and manage filters. Google does not publish one, so the community settled on @gongrzhe/server-gmail-autoauth-mcp, which runs on your own Mac over stdio against an OAuth client you create yourself. We ran it, spoke the protocol to it, and enumerated all 19 tools it exposes; the table below is that capture, word for word. What we could not do is complete an authenticated call: that needs a Google Cloud project with the Gmail API switched on and a finished browser consent flow, so this page shows you the tools and the exact errors you get without a token, and stops there. Two things are worth knowing before you start. The source repository is archived on GitHub and its last push was in August 2025, so nobody is merging fixes into it. The package still pulled 36,179 downloads in the last week anyway. [1][2][3][6][7]
Verification
Method
We spawned the server with npx over stdio with a placeholder OAuth client file and no saved token, completed the MCP initialize handshake, and called tools/list: the 19 tools below are that response, word for word. We then made one real tools/call, list_email_labels, and it failed, as it had to. Authenticated calls here are pending a Google OAuth token for a real Gmail account, which we do not have, so nothing on this page claims a successful Gmail read. Two details of the run: we pointed GMAIL_OAUTH_PATH and GMAIL_CREDENTIALS_PATH at a scratch folder so the test never touched a real ~/.gmail-mcp folder, and the startup output below is what npx printed, because the server itself prints no banner when it starts cleanly.
Startup banner
npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead npm warn deprecated uuid@9.0.1: uuid@10 and below is no longer supported. For ESM codebases, update to uuid@latest. For CommonJS codebases, use uuid@11 (but be aware this version will likely be deprecated in 2028).
One real tool call
tools/call list_email_labels {}Error: Failed to list labels: No access, refresh token, API key or refresh handler callback is set.
Real lines from the captured result: enough to prove the call answered.
Tools
The server answered tools/list with 19 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.
| Tool | What it does |
|---|---|
| send_emailto*subject*body*htmlBodymimeTypeccbccthreadIdinReplyToattachments | Sends a new email |
| draft_emailto*subject*body*htmlBodymimeTypeccbccthreadIdinReplyToattachments | Draft a new email |
| read_emailmessageId* | Retrieves the content of a specific email |
| search_emailsquery*maxResults | Searches for emails using Gmail search syntax |
| modify_emailmessageId*labelIdsaddLabelIdsremoveLabelIds | Modifies email labels (move to different folders) |
| delete_emailmessageId* | Permanently deletes an email |
| list_email_labels | Retrieves all available Gmail labels |
| batch_modify_emailsmessageIds*addLabelIdsremoveLabelIdsbatchSize | Modifies labels for multiple emails in batches |
| batch_delete_emailsmessageIds*batchSize | Permanently deletes multiple emails in batches |
| create_labelname*messageListVisibilitylabelListVisibility | Creates a new Gmail label |
| update_labelid*namemessageListVisibilitylabelListVisibility | Updates an existing Gmail label |
| delete_labelid* | Deletes a Gmail label |
| get_or_create_labelname*messageListVisibilitylabelListVisibility | Gets an existing label by name or creates it if it doesn't exist |
| create_filtercriteria*action* | Creates a new Gmail filter with custom criteria and actions |
| list_filters | Retrieves all Gmail filters |
| get_filterfilterId* | Gets details of a specific Gmail filter |
| delete_filterfilterId* | Deletes a Gmail filter |
| create_filter_from_templatetemplate*parameters* | Creates a filter using a pre-defined template for common scenarios |
| download_attachmentmessageId*attachmentId*filenamesavePath | Downloads an email attachment to a specified location |
Parameters marked with * are required.
Setup
Copy the block for the app you use. Each one is the configuration this server was verified with.
Open the file ~/Library/Application Support/Claude/claude_desktop_config.json (in Claude Desktop: Settings, then Developer, then Edit Config) and add:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"-y",
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}There is no credential in this file on purpose: the server reads two files out of ~/.gmail-mcp instead, the OAuth client file you put there and the token the one-time auth step writes. Put both in place first: with no client file the server exits before Claude Desktop can talk to it, and with no token it starts but every call comes back as an error. Then quit and reopen Claude Desktop. [10][5]
One command in your terminal:
claude mcp add gmail -- npx -y @gongrzhe/server-gmail-autoauth-mcp
Everything after the double dash is the exact command Claude Code will run, and it is the command we ran in the verification run. Run the one-time auth step before this one. [11]
Add to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"-y",
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}Cursor picks the file up on restart. Nothing secret goes in this file, so a project-level .cursor/mcp.json is safe to commit; the tokens live in ~/.gmail-mcp instead. [12]
No JSON file and no terminal for the connection itself. In Routines: Settings, then Assistant, then Connections, then Add MCP Server. Switch the form to Command (stdio) and enter:
Name Gmail Command npx Arguments -y @gongrzhe/server-gmail-autoauth-mcp
Leave Environment Variables empty unless you keep your credentials somewhere other than ~/.gmail-mcp, in which case set GMAIL_OAUTH_PATH and GMAIL_CREDENTIALS_PATH, one per line; that is how we pointed the verification run at a scratch folder. Click Test Connection first: a working server answers with its tool count, nineteen for this one. [13]
No terminal needed
This server has one unavoidable terminal step, so be honest with yourself about it before you start: you create a Google OAuth client, you run one command to sign in with it, and after that everything is clicks. Routines is a Mac app that runs MCP servers for you, and once this one is added its tools are available to your AI in chat and in scheduled routines.
01
Download the app from getroutines.ai/download, drag it to Applications, and sign in.
02
In Google Cloud Console create a project, or pick an existing one, and enable the Gmail API on it. Then open APIs and Services, then Credentials, then Create Credentials, then OAuth client ID, and choose Desktop app. Download the JSON file and rename it gcp-oauth.keys.json.
03
In Terminal: mkdir -p ~/.gmail-mcp, move gcp-oauth.keys.json into that folder, then run npx @gongrzhe/server-gmail-autoauth-mcp auth. Your browser opens, you approve the access, and the command saves a token as ~/.gmail-mcp/credentials.json. This is the only terminal step, and you do it once.
04
Click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server.
05
Switch the form to Command (stdio): this server is a command that runs on your Mac, not a web address. Name it Gmail. Command: npx. Arguments: -y @gongrzhe/server-gmail-autoauth-mcp. Leave Environment Variables empty; the server finds the two files in ~/.gmail-mcp by itself.
06
Click Test Connection: Routines starts the server and reports how many tools it found, nineteen for this one. Then click Add Server. The tools work in chat right away; to let a scheduled routine use them, open the routine, find the Tools & connections card, and tick the server under Apps.
Routine ideas
Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.
Every weekday at 8:00, search my Gmail for unread messages from the last day, group them into things that need a reply, things that are just information, and newsletters, and write me a short list with one suggested next step for each.
Every Friday at 16:00, search my Gmail for emails I sent this week that nobody replied to, list them with the recipient and the subject, and write the list to inbox-followups.md.
Every Sunday at 19:00, search my Gmail for newsletters received in the last seven days, summarise each one in two sentences, and put the summaries in a single note ordered by how useful they look to me.
Troubleshooting
Real errors captured during the verification run, printed exactly as the server returned them.
What you see
Error: OAuth keys file not found. Please place gcp-oauth.keys.json in current directory or /tmp/gmail-mcp-probe/home/.gmail-mcp
The fix
The server checks for the OAuth client file before it speaks a single word of MCP, and quits if it is missing. We triggered this on purpose by starting it with no keys file anywhere. The folder at the end of that line is the .gmail-mcp folder in your home directory, which on your Mac reads /Users/yourname/.gmail-mcp; ours pointed at a scratch folder so the test could not touch a real one. Put gcp-oauth.keys.json there, or set GMAIL_OAUTH_PATH to wherever you keep it.
What you see
Error: Invalid OAuth keys file format. File should contain either "installed" or "web" credentials.
The fix
The file exists and parses as JSON, but it is not the file Google gave you. We triggered this by pointing the server at a file containing nothing but empty braces. A real OAuth client download starts with either "installed" or "web" as its single top-level key, depending on whether you chose Desktop app or Web application when you created it. Download it again from the Credentials page rather than editing it by hand.
What you see
Error: Failed to list labels: No access, refresh token, API key or refresh handler callback is set.
The fix
This is the state our verification run was in, and it is worth understanding because it looks like a broken server when it is not. The OAuth client file only tells the server who is asking; the token that says Google agreed lives in a second file, credentials.json, and it is written by the one-time auth command. Run npx @gongrzhe/server-gmail-autoauth-mcp auth, approve the access in the browser, and restart your MCP client. The same message comes back if you deleted that file or moved it out of the folder the server reads.
The fix
The npx command belongs to Node.js. If Node is not installed on your Mac, every client on this page fails at the spawn step before the server can say anything. Install Node from nodejs.org, restart your MCP client, and try again.
FAQ
It is a small program that gives an AI assistant a set of Gmail actions: searching the inbox with normal Gmail search syntax, reading a message, sending and drafting mail with attachments, moving messages between labels, and creating or deleting labels and filters. It runs as a local process on your Mac and talks to your AI app over stdio, using an OAuth client you create in your own Google account. [5][6]
We started the server, completed the MCP handshake, and read the tool list off the wire; that part is measured, and the table above is the raw response. We also made one real tool call, list_email_labels, and it failed, because a real call needs a Google token for a real mailbox and we have none. So the tool list is evidence, and nothing on this page describes what a successful Gmail query returns. The errors we did get are printed in full in the troubleshooting section.
The running server exposes 19: mail (send_email, draft_email, read_email, search_emails, modify_email, delete_email), batch work (batch_modify_emails, batch_delete_emails), labels (list_email_labels, create_label, update_label, delete_label, get_or_create_label), filters (create_filter, list_filters, get_filter, delete_filter, create_filter_from_template) and attachments (download_attachment). The table above is the live tools/list output, word for word.
Not as of the date on this page. We looked for one under the obvious @google, @google-cloud and @googleworkspace npm scopes and found nothing, and the Model Context Protocol project's own reference server collection has no Gmail server in it either. Every Gmail MCP server you can install today, including the one on this page, is community built. [7]
Once, yes, and we would rather say so than pretend otherwise. The connection itself is three fields in Routines, or a small JSON edit in Claude Desktop and Cursor, but before any of that you have to create a Google OAuth client and run the package's auth command once so it can save a token. There is no way to do that sign-in from inside an MCP client, because the server expects the token to be on disk before it starts. [5][13]
Know what you are choosing. The GitHub repository behind this package is archived, so its 38 open issues and 32 open pull requests cannot be resolved upstream. Its last push was in August 2025, and the package on npm has not moved since either. It is still the one almost everybody installs: 36,179 downloads in the last week, against 1,725 for @shinzolabs/gmail-mcp, which is not archived and was last touched in November 2025. If you want a maintained codebase more than a popular one, that is the alternative to look at. One more oddity worth knowing: npm lists this package as ISC while the LICENSE file in the repository is MIT. [3][2][4][8][9]
No. Routines already ships a Gmail connector you turn on with a one-click sign-in, with no Google Cloud project to create and no key file to place, and its tokens stay on your Mac. Set this community server up instead if you want its wider tool set, in particular the filter and batch tools, or if you want the same Gmail access in Claude Desktop or Cursor as well. [13]
Sources
Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.
[1]
Latest version 1.1.11, published 2025-08-06. Declares the ISC license and a single maintainer, gongrzhe.
[2]
[3]
1,167 stars, 408 forks, archived, and a last push dated 2025-08-06, per the GitHub API. The 70 open items are 38 issues and 32 pull requests, counted separately through the GitHub search API.
[4]
MIT, copyright 2025 GongRzhe, as reported by the GitHub API for the repository.
[5]
The Google Cloud project and OAuth client steps, the auth command, and the client config shape.
[6]
Instantiates StdioServerTransport, and loads the OAuth key file before registering any handler.
[7]
No Gmail server among the project's own reference servers.
[8]
56 stars, not archived, and a last push dated 2025-11-25, per the GitHub API.
[9]
1,725 downloads for the week ending 2026-08-01.
[10]
The claude_desktop_config.json shape and where the file lives.
[11]
[12]
[13]
The built-in one-click Gmail connector and how Routines runs any MCP server.
This page describes Gmail as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.
Behind this directory
Routines, the app behind this directory, runs MCP servers like this one without a terminal: see how connectors work. Your notes stay markdown files on your Mac, there is no cloud bill, and it works offline. Download Routines