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)

Tool	Qué hace
`gmail_estado`	Estado de la cuenta: servidores, candados, etiquetas y nº de mensajes/no leídos
`gmail_listar_etiquetas`	Lista todas las etiquetas y carpetas del buzón
`gmail_listar`	Lista los mensajes más recientes de una etiqueta (paginado, no marca leído)
`gmail_buscar`	Busca por remitente, destinatario, asunto, texto, fechas, no leídos…
`gmail_buscar_gmail`	Busca con la sintaxis nativa de Gmail (`from:`, `has:attachment`, `newer_than:7d`, `label:`, `OR`, `-exclusión`…)
`gmail_leer`	Lee un mensaje completo (cabeceras, cuerpo, etiquetas, adjuntos)
`gmail_hilo`	Muestra la conversación entera a la que pertenece un mensaje
`gmail_descargar_adjunto`	Descarga un adjunto (base64 o a disco)

Escritura reversible (siempre disponibles)

Tool	Qué hace
`gmail_marcar_leido`	Marca leído / no leído
`gmail_destacar`	Destaca / quita destacado (estrella)
`gmail_etiquetar`	Añade o quita una etiqueta de Gmail sin mover el mensaje
`gmail_crear_etiqueta`	Crea una etiqueta nueva (admite anidadas: `Clientes/Activos`)
`gmail_guardar_borrador`	Guarda un borrador en Borradores (no envía)

Mover / archivar / papelera — requieren GMAIL_ALLOW_MODIFY=1

Tool	Qué hace
`gmail_mover`	Mueve un mensaje a otra etiqueta/carpeta
`gmail_archivar`	Saca el mensaje de la Bandeja de entrada (sigue en «Todos»; reversible)
`gmail_eliminar`	Envía a la Papelera (nunca borra permanente; recuperable)

Envío — requieren GMAIL_ALLOW_SEND=1

Tool	Qué hace
`gmail_enviar`	Envía un correo nuevo (con adjuntos opcionales)
`gmail_responder`	Responde a un mensaje (cita el original, mantiene el hilo)
`gmail_reenviar`	Reenvía un mensaje con sus adjuntos

🔒 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

Activa la verificación en dos pasos en la cuenta de Google.
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.
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:

Directorio → Plugins → Añadir marketplace → pega la URL de este repositorio → Sincronizar.
Instala el plugin gmail.
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.

gmail-mcp