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: Gmail MCP Server

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.

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