Gmail Storage & Cleanup MCP

Un plugin MCP local y específico para Codex y Claude Code que supervisa el almacenamiento compartido de Google y ayuda a recuperar espacio en Gmail mediante un flujo de limpieza determinista y centrado en la revisión.

Comprueba la cuota de almacenamiento de Google, encuentra candidatos grandes de limpieza de Gmail, explica cada decisión de seguridad y requiere confirmación antes de mover correos a la Papelera. Nunca elimina correos de forma permanente. Este repositorio no incluye credenciales.

Por qué existe esto

El plugin oficial de Gmail es la mejor opción para el trabajo general con la bandeja de entrada, como buscar correos, resumir hilos, redactar respuestas, reenviar y aplicar etiquetas.

Este proyecto se centra deliberadamente en un problema distinto: evitar que una cuenta de Google se quede sin almacenamiento sin borrar correos importantes a ciegas.

Esta comparación describe el enfoque documentado de cada plugin, no todas las capacidades que un conector upstream pueda añadir en el futuro.

Related MCP server: Gmail Guardian

Instalación

Requisitos: Python 3.12+, Git y una cuenta de Google con Gmail.

git clone https://github.com/ashutoshchaubeypm/Gmail-MCP-tool.git
cd Gmail-MCP-tool
./scripts/setup.sh

1. Crear las credenciales de Google

En Google Cloud Console:

1. Crea un proyecto y habilita la Gmail API y la Google Drive API.

2. Configura Google Auth Platform. Para pruebas personales, usa External/Testing y añade tu dirección de Gmail como usuario de prueba.

3. Crea un cliente OAuth con el tipo de aplicación Desktop app.

4. Abre .env y añade los valores generados:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

Autoriza una vez:

.venv/bin/python -m app.auth_cli

El token local se escribe en work/google-token.json. Tanto ese archivo como .env son ignorados por Git.

2. Instalar en Codex

Desde la raíz del repositorio:

codex plugin marketplace add "$PWD"
codex plugin add gmail-mcp-tool@personal

Inicia una nueva tarea de Codex y luego pregunta: “Revisa mi almacenamiento de Google y encuentra candidatos de limpieza de Gmail para revisión.”

3. Instalar en Claude Code

Desde la raíz del repositorio:

claude plugin marketplace add "$PWD"
claude plugin install gmail-mcp-tool@gmail-mcp-tool

Inicia una nueva sesión de Claude Code después de la instalación.

Herramientas específicas

• get_storage_quota — uso del almacenamiento compartido de Google

• scan_cleanup_candidates — descubrimiento de Gmail de solo lectura y puntuación determinista

• get_candidate_details — revisar un resultado del último escaneo

• move_message_to_trash — mueve un mensaje confirmado y no protegido a la Papelera

Las etiquetas protegidas incluyen STARRED, IMPORTANT, SENT y DRAFT. El correo ambiguo permanece en revisión. Un mensaje debe provenir del último escaneo antes de poder moverse, y la herramienta no puede actuar sobre los mensajes protegidos. El plugin no vacía la Papelera ni elimina mensajes de forma permanente.

Desarrollo

.venv/bin/python scripts/security_check.py
.venv/bin/python -m pytest -q

Código fuente del plugin: plugins/gmail-mcp-tool/

Alcance deliberado

• Previsión de almacenamiento y comprobaciones programadas de cuota

• Políticas de limpieza más transparentes y personalización de reglas

• Estimaciones agregadas de recuperación e informes de limpieza

• Clasificación opcional de candidatos ambiguos, sin eludir las protecciones deterministas

La búsqueda general en la bandeja de entrada, los resúmenes de correos, el borrador de respuestas y el reenvío se dejan intencionadamente al plugin oficial de Gmail.

Seguridad

Nunca hagas commit de .env, del JSON de OAuth descargado ni de work/google-token.json. Antes de publicar cambios, ejecuta python scripts/security_check.py. Si alguna vez se confirman credenciales, revócalas y gíralas inmediatamente: eliminarlas del último commit no es suficiente.

Con licencia MIT.