# 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:

```env
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`:

```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

```bash
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.*