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 sencer

• list_labels() — llista les etiquetes disponibles

• create_draft(to, subject, body, threadId?) — crea un esborrany (mai l'envia)

Related MCP server: Moist

Configuració

Cada persona necessita el seu propi projecte de Google Cloud i les seves pròpies credencials OAuth — no es comparteixen entre usuaris.

1. Crea un projecte a Google Cloud Console.

2. Activa la Gmail API (APIs y servicios → Library).

3. 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).

4. Afegeix els scopes:

   • https://www.googleapis.com/auth/gmail.readonly

   • https://www.googleapis.com/auth/gmail.compose

5. Crea unes credencials OAuth client ID de tipus "Web application", amb el redirect URI:

   http://localhost:8765/oauth2callback

6. Copia .env.example a .env i omple GMAIL_CLIENT_ID i GMAIL_CLIENT_SECRET.

7. Instal·la dependències i autoritza:

   npm install
   npm run auth

   Obre la URL que et mostra, autoritza amb el teu compte de Gmail, i copia el GMAIL_REFRESH_TOKEN resultant 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 auth i actualitzar GMAIL_REFRESH_TOKEN a .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.mjs

Reinicia 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.mjs

Es 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.

1. Instal·la Node.js (LTS) i, opcionalment, Git for Windows.

2. 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 agy no es reconeix, afegeix C:\Users\<usuari>\AppData\Local\agy\bin al PATH de l'usuari.

3. 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 .env

4. Omple .env amb les teves credencials i executa npm run auth (mateixos passos de la secció Configuració; el redirect URI http://localhost:8765/oauth2callback és el mateix a Windows).

5. Registra el servidor amb una ruta absoluta de Windows:

   claude mcp add gmail --scope user -- node C:\Users\<usuari>\gmail-mcp-server\index.mjs

   o, 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ú.