gmail-mcp

Gmail second account MCP server

Lee y escribe un buzón de Gmail desde Claude.ai y Claude Code. El conector de Gmail propio de Claude.ai gestiona una sola cuenta, por lo que esto existe para la segunda: ejecuta una instancia por buzón y cada conector llega exactamente a la dirección que se le ha dado.

Un buzón por instancia

La cuenta a la que sirve una instancia viene de GMAIL_CREDENTIALS_DIR, y nada más es accesible desde ese proceso. Esa separación es el objetivo, no una limitación: un borrador no puede acabar en el buzón equivocado cuando el servidor solo tiene un conjunto de credenciales.

Related MCP server: Gmail MCP Local Server

Herramientas

Lectura

Escritura

Las dos herramientas de envío están marcadas como destructivas y así lo indican en sus descripciones: llegan a otras personas y no se pueden deshacer. La forma segura es gmail_create_draft, revisarlo y luego gmail_send_draft una vez que una persona haya aprobado el texto.

Búsqueda

gmail_search acepta los mismos operadores que el cuadro de búsqueda de Gmail:

is:unread from:client.com
subject:invoice has:attachment newer_than:7d
label:important -in:trash

Devuelve cabeceras y un fragmento por mensaje en lugar de los cuerpos, por lo que una búsqueda amplia sigue siendo ligera. Continúa con gmail_get_message o gmail_get_thread.

Cómo encaja todo

Claude.ai / Claude Code
        |  HTTPS
   Cloudflare Tunnel, or any proxy that gives you HTTPS
        |
   nginx  127.0.0.1:8461
        |
   auth-server.js  :8462    handles the login and the tokens
        |
   gmail-mcp  :8460         the server itself, local only
        |
   gmail.googleapis.com

El MCP no tiene inicio de sesión propio y no escucha en nada que no sea la máquina local, por lo que todo lo que llega a él ya ha pasado el inicio de sesión.

Configuración

Necesitas un cliente OAuth de Google Cloud con la API de Gmail habilitada y un token de actualización para el buzón. El directorio de credenciales contiene dos archivos:

credentials.json        {"refresh_token": "..."}
gcp-oauth.keys.json     the downloaded OAuth client

gmail.modify es el alcance que se debe conceder. Cubre lectura, etiquetado, redacción y envío; reduce a gmail.readonly más gmail.compose si prefieres que las propias credenciales no puedan enviar.

git clone https://github.com/rollecode/gmail-second-account-mcp.git
cd gmail-second-account-mcp
uv venv && uv pip install -e .
npm install --omit=dev

CONFIG_DIR=~/.config/gmail-mcp node set-password.js 'your-password-here'
openssl rand -hex 32 > ~/.config/gmail-mcp/token
chmod 600 ~/.config/gmail-mcp/token

Rellena YOUR_USER, el nombre de host y el directorio de credenciales en systemd/*.service y nginx/gmail-mcp.conf, y luego:

sudo cp systemd/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now gmail-mcp gmail-mcp-auth

sudo cp nginx/gmail-mcp.conf /etc/nginx/sites-enabled/gmail-mcp
sudo nginx -t && sudo systemctl reload nginx

Apunta un túnel o un proxy HTTPS a 127.0.0.1:8461. OAuth necesita HTTPS.

Comprueba desde fuera: el descubrimiento devuelve metadatos, y /mcp sin token debe devolver 401.

curl https://your-host/.well-known/oauth-authorization-server
curl -o /dev/null -w '%{http_code}\n' -X POST https://your-host/mcp

Conexión

Claude.ai: Ajustes, Conectores, Añadir conector personalizado, https://your-host/mcp, ID de cliente y secreto en blanco.

Claude Code:

claude mcp add --transport http gmail https://your-host/mcp \
  --header "Authorization: Bearer $(cat ~/.config/gmail-mcp/token)" --scope user

Localmente a través de stdio, sin servidor alguno:

GMAIL_CREDENTIALS_DIR=/path/to/creds claude mcp add gmail -- /path/to/.venv/bin/gmail-mcp

Ajustes

Los tokens de acceso se renuevan en memoria cuando caducan; solo el token de actualización se lee del disco.

Créditos

La capa de inicio de sesión proviene de rollecode/obsidian-remote-mcp.