# 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)

## 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](https://console.cloud.google.com).
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](https://nodejs.org) (LTS) i, opcionalment, [Git for Windows](https://git-scm.com/download/win).
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ú.