gmail-mcp-server
Provides tools for searching emails, reading full emails, listing labels, and creating drafts in Gmail, without sending or deleting messages.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gmail-mcp-server Search my Gmail for unread messages from my manager and read the most recent one"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
gmail-mcp-server
Servidor MCP (Model Context Protocol) mínim per a Gmail. Exposa 4 eines de només lectura/esborrany — no hi ha cap eina per enviar ni esborrar correus.
Eines
search_emails(query, maxResults)— cerca amb la sintaxi de cerca de Gmail (label:,from:,is:unread, etc.)read_email(messageId)— llegeix un correu sencerlist_labels()— llista les etiquetes disponiblescreate_draft(to, subject, body, threadId?)— crea un esborrany (mai l'envia)
Related MCP server: email-mcp
Configuració
Cada persona necessita el seu propi projecte de Google Cloud i les seves pròpies credencials OAuth — no es comparteixen entre usuaris.
Crea un projecte a Google Cloud Console.
Activa la Gmail API (APIs y servicios → Library).
Configura la OAuth consent screen: tipus "Internal" si el compte és d'un Google Workspace, o "External" en mode de prova si és un Gmail personal (afegeix-te com a usuari de prova).
Afegeix els scopes:
https://www.googleapis.com/auth/gmail.readonlyhttps://www.googleapis.com/auth/gmail.compose
Crea unes credencials OAuth client ID de tipus "Web application", amb el redirect URI:
http://localhost:8765/oauth2callbackCopia
.env.examplea.envi ompleGMAIL_CLIENT_IDiGMAIL_CLIENT_SECRET.Instal·la dependències i autoritza:
npm install npm run authObre la URL que et mostra, autoritza amb el teu compte de Gmail, i copia el
GMAIL_REFRESH_TOKENresultant a.env.
Gmail personal (@gmail.com) vs. Google Workspace
Amb un compte de Google Workspace (d'una organització/empresa), pots triar el tipus "Internal" a la OAuth consent screen: el refresh token no caduca i tot funciona sense límits addicionals.
Amb un Gmail personal, no existeix l'opció "Internal" — cal anar per "External". Mentre l'app estigui en mode Testing (l'estat per defecte, sense verificar per Google), hi ha dues limitacions importants:
El refresh token caduca cada 7 dies. Passat aquest temps, cal tornar a executar
npm run authi actualitzarGMAIL_REFRESH_TOKENa.env, o el servidor deixarà de poder autenticar-se.Màxim 100 usuaris de prova poden autoritzar l'app.
Aquestes limitacions només desapareixen si es passa l'app pel procés de verificació de Google (obligatori per als scopes de Gmail, ja que es consideren sensibles/restringits): auditoria de seguretat, política de privacitat pública, domini verificat, etc. És un procés de setmanes pensat per a apps distribuïdes a molts usuaris — normalment no val la pena per a un ús personal com aquest. Si el token et caduca sovint, el més senzill és re-executar npm run auth cada vegada.
Registrar-lo a Claude Code
claude mcp add gmail --scope user -- node /ruta/absoluta/a/gmail-mcp-server/index.mjsReinicia Claude Code perquè detecti el servidor nou.
Registrar-lo a Antigravity CLI (Google)
La Gemini CLI ja no funciona amb comptes individuals; l'alternativa de Google és l'Antigravity CLI (agy):
agy mcp add gmail node /ruta/absoluta/a/gmail-mcp-server/index.mjsEs desa a ~/.gemini/config/mcp_config.json (a Windows, dins del directori d'usuari). Les eines són les mateixes.
Windows
El servidor funciona igual a Windows 10/11; només canvia la instal·lació i les rutes.
Instal·la Node.js (LTS) i, opcionalment, Git for Windows.
Instal·la el client d'IA a PowerShell (no cal ser administrador):
Claude Code:
irm https://claude.ai/install.ps1 | iex(requereix un compte de pagament de Claude)Antigravity CLI:
irm https://antigravity.google/cli/install.ps1 | iex
Tanca i reobre PowerShell perquè s'actualitzi el PATH. Si
agyno es reconeix, afegeixC:\Users\<usuari>\AppData\Local\agy\binal PATH de l'usuari.Clona el repositori i instal·la les dependències:
git clone https://github.com/fbassas/gmail-mcp-server.git cd gmail-mcp-server npm install copy .env.example .envOmple
.envamb les teves credencials i executanpm run auth(mateixos passos de la secció Configuració; el redirect URIhttp://localhost:8765/oauth2callbackés el mateix a Windows).Registra el servidor amb una ruta absoluta de Windows:
claude mcp add gmail --scope user -- node C:\Users\<usuari>\gmail-mcp-server\index.mjso, per a Antigravity:
agy mcp add gmail node C:\Users\<usuari>\gmail-mcp-server\index.mjs
Seguretat
El fitxer .env conté credencials personals i mai s'ha de pujar a git (ja està al .gitignore). No compartisis el teu GMAIL_REFRESH_TOKEN amb ningú.
Available Tools
4 toolscreate_draftB
Crea un esborrany de correu a Gmail. Aquesta eina mai envia correus.
Inputs: to (required), body (required), subject (required), threadId.
list_labelsA
Llista totes les etiquetes de Gmail (de sistema i personalitzades) amb el seu nom i id.
Inputs: no named parameters.
read_emailB
Llegeix el contingut complet d'un correu pel seu ID de missatge.
Inputs: messageId (required).
search_emailsB
Cerca correus a Gmail fent servir la sintaxi de cerca de Gmail (p. ex. 'from:algu@exemple.com is:unread').
Inputs: query (required), maxResults.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a clearly distinct operation: searching messages (returns IDs), listing labels, reading a single message by ID, and creating a draft. There is no plausible way to confuse search_emails with read_email since one locates and the other fetches content, and list_labels is orthogonal to all of them.
All four tools follow a strict verb_noun snake_case pattern (search_emails, list_labels, read_email, create_draft) with the verb accurately reflecting the action (search/list/read/create). No mixing of conventions.
Four tools is thin for a full Gmail integration — the surface is essentially 'read + draft'. It is not bloated, but most real email workflows would need more than this, putting it on the borderline of under-scoped.
Core read path is covered (search → read) plus labels and draft creation, but there are notable gaps: no send_email, no reply/forward, no label application or modification, no delete/archive, and no thread listing. The draft-only design may be deliberate for safety, but agents attempting to actually send a message will hit a dead end.
Related MCP Connectors
Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflow…
Manage Gmail messages, threads, labels, drafts, and settings from your workflows. Send and organiz…
Permissioned access to Gmail, Drive and Calendar via the user's own Google account
Search Gmail and Outlook, save drafts, manage email rules, and view email stats.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to Gmail, enabling email search, unread listing, message and thread retrieval, and draft reply preparation without sending.ISC
- FlicenseNot gradedqualityDmaintenanceEnables searching contacts, drafting, and sending emails via the Gmail API with explicit user approval required before sending.-
- AlicenseAqualityBmaintenanceEnables AI assistants to search, read, draft, and send Gmail messages, as well as manage labels and trash using natural language.24127 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables natural-language interaction with Gmail, including reading, searching, drafting, and managing emails, with safety features like read-only mode and bounded reads.Apache 2.0