gmail-mcp

Un servidor MCP de Gmail con múltiples cuentas para agentes de IA (Claude Code y cualquier otra cosa que hable MCP), con un objetivo de diseño por encima de todo: el agente puede leer y redactar libremente, pero un humano debe aprobar cada envío.

Creado porque los conectores Gmail alojados vinculan una cuenta a la vez y envían sin fricción. Este servidor vincula cualquier número de cuentas de Gmail detrás de alias cortos (work, school, ...) y divide las capacidades según el riesgo:

El servidor se registra como gmail-accounts (no gmail) a propósito: si además ejecutas un conector Gmail alojado, nombres de herramientas casi idénticos hacen que un agente lea la bandeja de entrada equivocada y notifique un falso negativo con total seguridad.

Cómo funciona el control de envío

1. El agente prepara un borrador y te pide que lo apruebes.

2. Ejecutas gmail-approve en tu propia terminal, revisas la carga útil RFC822 exacta y obtienes un token de un solo uso vinculado al hash de contenido de ese borrador.

3. El agente llama a la herramienta de envío con el token. Borrador incorrecto, borrador editado, token reutilizado, token caducado: todo se rechaza.

La herramienta de envío también lleva anthropic/requiresUserInteraction, por lo que Claude Code solicita la intervención de un humano incluso en modo bypassPermissions. El CLI de token es un mecanismo de interbloqueo contra errores; el prompt del harness es el límite que se hace cumplir.

Related MCP server: Gmail Multi-Inbox MCP Server

Configuración

Requiere Python 3.12+ y uv.

1. Cliente OAuth de Google Cloud

Crea un proyecto en console.cloud.google.com, habilita la API de Gmail, crea un ID de cliente OAuth de tipo Aplicación de escritorio y descarga el JSON a:

~/.config/gmail-mcp/client_secret.json

2. Declara tus cuentas

~/.config/gmail-mcp/accounts.json:

{
  "accounts": [
    { "alias": "personal", "email": "alice.personal@gmail.com" },
    { "alias": "work",     "email": "alice.work@gmail.com" }
  ]
}

Añadir una cuenta más adelante es una edición de configuración más una autenticación; el archivo se vuelve a leer en cada llamada, por lo que no es necesario reiniciar.

3. Autoriza cada cuenta

uv sync
scripts/auth-all.sh          # runs the OAuth flow once per alias, skips done ones

Cada permiso concedido se verifica contra su alias: autorizar la cuenta de Google equivocada en el navegador se detecta y se rechaza, no se almacena silenciosamente.

4. Regístralo con Claude Code

claude mcp add gmail-accounts -- uv run --directory /path/to/gmail-mcp --frozen --no-sync gmail-mcp

Uso diario

Cada herramienta toma un alias account. Pídele al agente cosas como "busca en work el hilo de la factura" o "redacta una respuesta en personal". Cuando llegue el momento de enviar:

gmail-approve            # lists pending sends, shows the payload, mints a token

Comprobación de estado:

uv run gmail-mcp-health

Notas de seguridad

• Los secretos nunca entran en el repositorio: client_secret.json y los tokens por cuenta viven en ~/.config/gmail-mcp/ (se puede sobrescribir con GMAIL_MCP_CONFIG).

• Todas las escrituras de configuración son atómicas (tmp + fsync + rename); un fallo a mitad de escritura nunca deja un archivo incompleto.

• stdout es el canal JSON-RPC; nada en el paquete puede usar print() (aplicado por ruff T201), por lo que los diagnósticos no pueden corromper el protocolo.

Pruebas

uv run pytest