
MCP server for the Gmail API — search, read and send email, manage drafts, labels and the trash. For
MCP server for the Gmail API — search, read and send email, manage drafts, labels and the trash. For Claude, Cursor, Codex and other AI clients.
·
English | Русский
A1 Gmail MCP lets an AI app work with your Gmail mailbox in plain language. Search and read mail, prepare replies as drafts, send them when you are ready, keep labels tidy and use the trash instead of permanent deletion.
It uses the Gmail API with your Google account. It distinguishes a draft you can still edit from a sent email that cannot be recalled, and makes the limits of the Gmail API explicit instead of implying that every mail task is reversible.
127.0.0.1 with PKCE and keeps the tokens itself — no config files, no restart.gmail.modify only — no permanent deletion and no access to Gmail settings.Start with a read-only question:
Show my unread emails from the last week and tell me which ones need a reply.
Connect the server · Explore use cases · Open technical documentation
You: What is unread in my inbox from this week about the Acme contract?
Assistant: Searches with Gmail query syntax and shows senders, subjects, dates and snippets. Nothing changes.
You: Draft a reply to the latest one: we send the signed copy on Friday.
Assistant: Creates a draft in the same thread and shows it for review. Nothing is sent.
You: Send it.
Assistant: Sends the draft. Sending is a separate, explicitly destructive step, so your AI app can ask for confirmation first.
You need Node.js 20+ and a Google account. Credentials are not required at install time — the server connects from the conversation.
In the app: open Settings → MCP servers, select Add server, choose STDIO, enter the command npx -y mcp-google-gmail@latest and environment variables GOOGLE_GMAIL_CLIENT_ID, GOOGLE_GMAIL_CLIENT_SECRET, GOOGLE_GMAIL_REFRESH_TOKEN, then select Save and Restart.
From the command line:
codex mcp add google-gmail \
-- npx -y mcp-google-gmail@latestcodex mcp listclaude mcp add \
--transport stdio --scope user google-gmail \
-- npx -y mcp-google-gmail@latestclaude mcp listThe current official path is Settings → Extensions. For a custom desktop extension, open Advanced settings → Extension Developer → Install Extension…, select a .mcpb file and follow the prompts.
This repository currently publishes an npm stdio package and does not contain a .mcpb bundle. For Claude Desktop builds that still support local configuration, use the following JSON stdio configuration as a fallback:
{
"mcpServers": {
"google-gmail": {
"command": "npx",
"args": ["-y", "mcp-google-gmail@latest"]
}
}
}In those builds, save it to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.
Add this to ~/.cursor/mcp.json on macOS/Linux or %USERPROFILE%\.cursor\mcp.json on Windows:
{
"mcpServers": {
"google-gmail": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-google-gmail@latest"]
}
}
}Run MCP: Open User Configuration and add:
{
"servers": {
"google-gmail": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-google-gmail@latest"]
}
}
}Check it with MCP: List Servers.
Receipts/2026 and apply it to the matching messages.create_draft prepares the email, get_draft shows it for review, send_draft sends it. send_message skips the draft and sends immediately.5xx error the server does not re-send; search in:sent before trying again, because a replayed send would be a double-sent email.manage_trash is reversible for about 30 days; there is deliberately no permanent-delete tool.update_draft replaces the whole draft (the API has no partial edit) and delete_draft is permanent, because drafts skip the trash.Every call works on one mailbox — the account that granted the token. Decoded bodies are truncated at a configurable limit with explicit flags, and attachments come back as metadata only; attachment content is fetched through raw_request deliberately.
| Operation | What happens | Confirmation boundary |
|---|---|---|
| Search and read messages, threads, drafts, labels, the profile | Reads mailbox data | No change |
| Create or update a draft | Prepares or replaces an unsent email | Changes the mailbox |
| Change read, starred or archived state, apply or strip labels | Changes how mail is organized | Changes the mailbox |
| Create or rename a label | Changes the label vocabulary | Changes the mailbox |
| Trash or untrash a message or thread | Moves mail to or from the trash; reversible for ~30 days | Destructive |
| Send an email or a draft | Delivers mail to real recipients; cannot be unsent | Destructive |
| Delete a draft or a label | Removes it permanently, skipping the trash | Destructive |
| Raw API request | Can call API methods without a dedicated tool | Potentially destructive |
The AI client controls confirmation prompts. The server marks reads, writes and destructive tools so the client can distinguish an inspection from a live change.
Google Gmail requires OAuth 2.0; an API key is not enough. There are two ways in, and the first one needs no configuration files.
Say "connect Gmail" and the assistant runs the flow with you:
setup_instructions prints the checklist: create or select a Google Cloud project, enable Gmail API, configure the consent screen and create a Desktop app OAuth client.set_client stores it owner-only. The secret never goes through the conversation.start_login returns a Google consent link. Open it on this machine and approve; the code comes back to a one-shot listener on 127.0.0.1 (PKCE), never through the chat.finish_login exchanges the code and saves the tokens to ~/.config/mcp-google-gmail/credentials.json (mode 0600) and verifies them with a real Gmail API call — so an API that is still switched off is caught right there.The tokens are re-read on every call, so the connection works immediately — no restart of the AI app. auth_status shows what is connected, logout revokes and deletes it.
Create or select a Google Cloud project and enable the Gmail API.
Configure the OAuth consent screen and create a Desktop app OAuth client.
Authorize the Google account whose mailbox you want to connect — every call works on that one mailbox. The OAuth 2.0 Playground can obtain the refresh token when Use your own OAuth credentials is enabled.
Request the scope:
https://www.googleapis.com/auth/gmail.modifyIt covers search, reading, sending, drafts, labels and the trash — but not permanent deletion and not Gmail settings. Permanent deletion through raw_request additionally requires the full https://mail.google.com/ scope.
Testing-mode OAuth refresh tokens can expire after seven days. Publish the OAuth app, or use an Internal app in a Workspace domain, when you need long-lived access. Treat the client secret and refresh token as passwords.
Every variable is optional — with none of them the server connects from the chat.
| Variable | Required | Description |
|---|---|---|
GOOGLE_GMAIL_CLIENT_ID | No* | OAuth client ID. |
GOOGLE_GMAIL_CLIENT_SECRET | No* | OAuth client secret. |
GOOGLE_GMAIL_REFRESH_TOKEN | No* | OAuth refresh token. |
GOOGLE_GMAIL_ACCESS_TOKEN | No* | Short-lived alternative to the OAuth trio (about 1 hour). |
GOOGLE_GMAIL_OAUTH_PORT | No | Fixed loopback port for the in-chat login; useful over SSH port forwarding. |
GOOGLE_GMAIL_API_BASE | No | Gmail API base URL override. |
GOOGLE_GMAIL_TIMEOUT_MS | No | Per-request timeout; default 60000 ms. |
GOOGLE_GMAIL_MAX_RETRIES | No | Temporary-error retries; default 3. |
* Provide either the OAuth trio or an access token.
#; a value from your request can appear in it if the error text contains it. Set ASKADS_TELEMETRY=0 to opt out.429, the server uses backoff; reads also retry after network and 5xx errors, while sends and other writes are never replayed after an uncertain failure.raw_request can also reach history.list for incremental sync.Found a bug or need a scenario? Create an issue or write in Telegram.
You made it to the end!
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add google-gmail -- npx -y mcp-google-gmail@latest{
"mcpServers": {
"google-gmail": {
"args": [
"-y",
"mcp-google-gmail@latest"
],
"command": "npx"
}
}
}code --add-mcp '{"name":"google-gmail","args":["-y","mcp-google-gmail@latest"],"command":"npx"}'[mcp_servers.google-gmail]
command = "npx"
args = ["-y", "mcp-google-gmail@latest"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/gmail-mcp to learn what the "Gmail MCP" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
| Name | What it does |
|---|---|
auth_status | Shows whether this server is connected to Google: token presence and source (env variables or a stored in-chat login), expiry, the Google account email, granted vs missing OAuth scopes, where the cred |
setup_instructions | Step-by-step checklist for connecting this server to Google: creating a Google Cloud project and a Desktop-app OAuth client, publishing the consent screen (mandatory — Testing-mode refresh tokens die |
set_client | Saves the OAuth client credentials from the JSON file downloaded from Google Cloud Console ('Download JSON' on a Desktop-app client). Pass the file PATH — the secret must never be pasted into the chat |
start_login | First step of connecting from the chat, without editing config files or restarting the client. Returns authorizeUrl — show it to the user as a clickable link and ask them to open it in the browser ON |
finish_login | Second step: confirms the browser consent finished, saves the tokens to an owner-only file and verifies the login with a read-only identity call, returning the account email and the granted scopes. Af |
logout | Revokes the stored token at Google (oauth2.googleapis.com/revoke) and deletes the local credentials file. Tokens supplied via env variables are NOT touched — remove them from the MCP client config man |
list_messages | Searches the mailbox with Gmail query syntax and returns one summary per message: id, threadId, labelIds, snippet, from, to, subject, date, internalDate. Filter with query (same operators as the Gmail |
get_message | Fetches one message fully decoded: headers (from, to, cc, subject, date, messageId, inReplyTo, references — RFC 2047 words decoded), the plain-text body (base64/charset decoded), the HTML body when th |
send_message | Sends an email from the authenticated mailbox, immediately and irreversibly. Requires at least one recipient across to/cc/bcc (a bcc-only send is fine — to may be omitted) and at least a subject or a |
modify_message | Changes a message's state via Gmail labels: read=true/false marks read/unread, starred=true/false stars/unstars, archived=true removes it from the inbox (archived=false moves it back), and add_label_i |
manage_trash | Moves a message or a whole thread to the Gmail trash, or restores it. action=trash is REVERSIBLE: Gmail keeps trashed mail for about 30 days, then deletes it permanently; action=untrash restores it be |
list_threads | Searches conversations (threads) with the same Gmail query syntax as list_messages and returns id, snippet (of the latest message) and historyId per thread. Use this instead of list_messages when the |
get_thread | Fetches a conversation with every message decoded like get_message: headers, text bodies (HTML only when a message has no text part or include_html=true), attachment metadata and truncation flags. Mes |
modify_thread | Applies the same normalized state changes as modify_message — read/unread, starred, archived, add_label_ids/remove_label_ids — to EVERY message in a conversation at once. Use it to mark a whole conver |
create_draft | Creates a draft email in the mailbox without sending anything. All fields are optional — an empty draft is legal — but a useful one carries to[], subject and a body. For a reply draft set thread_id, i |
list_drafts | Lists the mailbox's drafts: draft id plus the underlying message's id and threadId (no subjects — read one with get_draft). query filters with Gmail query syntax (e.g. subject:invoice); paginate with |
get_draft | Fetches one draft with its message decoded like get_message: headers (to, cc, subject, ...), text body, HTML only on request, attachment metadata. Use it to show the user what send_draft would send, o |
update_draft | REPLACES a draft's entire message — the Gmail API has no partial draft edit, so omitted fields are dropped, not kept. Read the current content with get_draft first, then pass the complete new state (r |
send_draft | Sends an existing draft exactly as it is stored, immediately and irreversibly; the draft disappears from the drafts list and becomes a sent message (returned id/threadId). Verify the content with get_ |
delete_draft | PERMANENTLY deletes a draft — drafts skip the trash, so there is no undo and no manage_trash recovery. Confirm with get_draft before deleting anything the user might still want. Returns empty on succe |
list_labels | Without label_id: lists every label in the mailbox — system labels (INBOX, SENT, DRAFT, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, CATEGORY_*) and user labels with their ids — the vocabulary that list_m |
manage_labels | Manages user labels. action=create needs name (nest with "/", e.g. "Clients/Acme" — the parent must already exist). action=update needs label_id plus at least one of name, label_list_visibility (show |
get_profile | Returns the authenticated mailbox's profile: emailAddress (the user's own address — useful for send-to-self checks and for recognizing the user's messages in threads), messagesTotal, threadsTotal and |
raw_request | Escape hatch to call any Gmail API v1 path directly, for requests the typed tools don't cover — e.g. downloading attachment content ("gmail/v1/users/me/messages/<messageId>/attachments/<attachmentId>" |
Read live from the server on October 11, 2026.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/gmail-mcp)Nothing comparable is listed yet.
v1.1.2Release notesv1.1.1Release notesv1.1.0Release notesv1.0.0Release notesv0.2.0Release notesv0.1.0Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "gmail-mcp" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.