gmail-mcp · MCP de Gmail para Claude

Servidor MCP (Model Context Protocol) que da a un agente (Claude Desktop, Claude Code, Cowork…) control completo sobre una cuenta de Gmail o Google Workspace: leer, buscar con la sintaxis nativa de Gmail, ver hilos, descargar adjuntos, etiquetar, archivar, enviar, responder, reenviar, guardar borradores y enviar a la papelera.

Funciona por IMAP/SMTP con una contraseña de aplicación de Google: no hay que crear un proyecto en Google Cloud ni pasar por pantallas de verificación de OAuth.

🔒 Sin credenciales en el repositorio. Todo se configura por variables de entorno. La cuenta y la contraseña de aplicación las pone quien instala el MCP; aquí no hay ningún secreto.

🧰 Herramientas (19)

Lectura (siempre disponibles)

Escritura reversible (siempre disponibles)

Mover / archivar / papelera — requieren GMAIL_ALLOW_MODIFY=1

Envío — requieren GMAIL_ALLOW_SEND=1

Related MCP server: Gmail MCP Server

🔒 Seguridad

• Candados por variable de entorno, apagados por defecto: enviar (GMAIL_ALLOW_SEND) y mover/archivar/papelera (GMAIL_ALLOW_MODIFY). Con ellos apagados, esas tools devuelven un error claro y no hacen nada.

• Leer nunca marca como leído (usa BODY.PEEK / EXAMINE).

• No existe borrado permanente: «eliminar» mueve a la Papelera, recuperable (Gmail la purga a los 30 días).

• El .env con las credenciales está en .gitignore y no se sube.

⚙️ Instalación

1) Requisitos

• Python 3.9+

• pip install -r requirements.txt

2) Contraseña de aplicación de Google

1. Activa la verificación en dos pasos en la cuenta de Google.

2. Ve a https://myaccount.google.com/apppasswords y crea una contraseña de aplicación (16 caracteres). Esa es la que usa este MCP — no la contraseña normal de la cuenta.

3. Comprueba que IMAP está activado: Gmail → ⚙️ Configuración → Reenvío y correo POP/IMAP → Habilitar IMAP.

3) Configuración

Copia .env.example a .env y rellena tu cuenta:

GMAIL_USER=tucuenta@gmail.com
GMAIL_APP_PASSWORD=xxxxxxxxxxxxxxxx
GMAIL_ALLOW_SEND=0
GMAIL_ALLOW_MODIFY=0

(Alternativamente puedes pasar esas variables como env en la configuración del cliente MCP, sin fichero .env.)

4a) Registrar en Claude Desktop

En claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["C:/ruta/a/gmail-mcp/server.py"],
      "env": {
        "PYTHONUTF8": "1",
        "GMAIL_USER": "tucuenta@gmail.com",
        "GMAIL_APP_PASSWORD": "xxxxxxxxxxxxxxxx",
        "GMAIL_ALLOW_SEND": "0",
        "GMAIL_ALLOW_MODIFY": "0"
      }
    }
  }
}

Reinicia Claude Desktop después de editarlo.

4b) Instalar en Cowork / Claude Code por URL (como plugin)

Este repo incluye .claude-plugin/marketplace.json, así que se puede añadir por URL:

1. Directorio → Plugins → Añadir marketplace → pega la URL de este repositorio → Sincronizar.

2. Instala el plugin gmail.

3. Configura las variables de entorno (cuenta y contraseña de aplicación) en el cliente. Requiere Python + dependencias instaladas en la máquina donde corre el MCP.

🧪 Validación

python test_gate.py

Descubre todas las tools por el protocolo MCP, prueba las de lectura con datos reales, verifica que los candados bloquean el envío y el borrado, y hace el handshake MCP por stdio. No envía nada a terceros ni borra ningún correo.

💡 Ejemplos de uso

• «¿Qué correos sin leer tengo hoy?» → gmail_listar / gmail_buscar

• «Busca los correos del juzgado con PDF del último mes» → gmail_buscar_gmail("from:juzgado has:attachment newer_than:1m")

• «Enséñame la conversación completa con este cliente» → gmail_hilo

• «Etiqueta este correo como Clientes/Activos y sácalo de la bandeja» → gmail_etiquetar + gmail_archivar

• «Guárdame un borrador de respuesta» → gmail_guardar_borrador

Genérico y sin datos personales en el código. Configúralo con tu propia cuenta.