Servidor MCP de limpieza de Gmail

Un servidor Model Context Protocol centrado en la limpieza de la bandeja de entrada de Gmail: elimina correos, gestiona filtros y extrae enlaces de cancelación de suscripción. Diseñado para complementar el conector Gmail integrado de Anthropic, que se encarga de leer, buscar, redactar y enviar.

Bifurcación corregida de dcerniglia/gmail-cleanup-mcp (licencia MIT). Esta bifurcación corrige un error por el que search_and_trash y batch_trash_emails descartaban silenciosamente los fallos en lugar de reintentarlos: lanzar 50 solicitudes de borrado simultáneas podía superar el límite de frecuencia de Gmail y descartar ~la mitad del lote sin mostrar ningún error. Ahora ambas herramientas procesan lotes más pequeños, aplican retroceso, reintentan automáticamente y notifican el error real por mensaje fallido.

Herramientas

Related MCP server: Gmail AutoAuth MCP Server

Requisitos previos

• Node.js 18+

• Un proyecto de Google Cloud con la API de Gmail habilitada

• Credenciales OAuth 2.0 (tipo aplicación de escritorio)

Configuración

1. OAuth de Google Cloud

¿Ya tienes ~/.gmail-mcp/gcp-oauth.keys.json de otro servidor MCP de Gmail? Ve directamente al paso 2: este servidor usa la misma ubicación de credenciales.

1. Ve a Google Cloud Console

2. Crea un proyecto (o reutiliza uno existente) y habilita la API de Gmail

3. Ve a Credenciales → Crear credenciales → ID de cliente OAuth

4. Elige Aplicación de escritorio, descarga el JSON

5. Guárdalo como ~/.gmail-mcp/gcp-oauth.keys.json (o coloca gcp-oauth.keys.json en el directorio del proyecto: se copiará automáticamente en el primer inicio)

2. Instalación y compilación

git clone https://github.com/davidcerniglia/gmail-cleanup-mcp.git
cd gmail-cleanup-mcp
npm install
npm run build

3. Autenticación

npm run auth

Esto abre un navegador para el consentimiento OAuth de Google. Las credenciales se guardan en ~/.gmail-mcp/credentials.json con permisos 0600 (solo propietario).

4. Añadir a Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "gmail-cleanup": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-cleanup-mcp/dist/index.js"]
    }
  }
}

O, para Claude Code, añade a .claude/settings.json:

{
  "mcpServers": {
    "gmail-cleanup": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-cleanup-mcp/dist/index.js"]
    }
  }
}

Ejemplos de uso

Cómo funciona con el Gmail integrado de Claude

Seguridad

• Ámbitos mínimos: gmail.modify + gmail.settings.basic: lo mínimo necesario para las operaciones de papelera y filtros

• Papelera, no borrado definitivo: todas las eliminaciones usan la papelera de Gmail (ventana de recuperación de 30 días), nunca el borrado permanente

• Modo de prueba: search_and_trash puede previsualizar las coincidencias antes de confirmar

• Permisos de archivo restrictivos: las credenciales se almacenan con 0600 (solo lectura/escritura del propietario)

• Sin gestión de archivos adjuntos: riesgo cero de salto de directorio

• Sin acceso al sistema de archivos más allá del almacenamiento de credenciales en ~/.gmail-mcp/

Variables de entorno

Licencia

MIT