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

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.