Gmail MCP Server

Este proyecto implementa un servidor del Model Context Protocol (MCP) que permite la interacción con cuentas de Gmail mediante IMAP y SMTP. Proporciona herramientas para buscar correos electrónicos, recuperar contenido, gestionar etiquetas (crear, eliminar, renombrar, aplicar, quitar) y enviar/reenviar correos.

Características

• Búsqueda de correos: Busca correos por rango de fechas, palabra clave o cadena de consulta de Gmail sin procesar. Admite la búsqueda en carpetas específicas (recibidos, enviados) y la limitación de resultados. Utiliza la extensión X-GM-RAW de Gmail para una búsqueda eficiente en la bandeja de entrada (p. ej., filtrando por category:primary).

• Recuperación de contenido de correos: Obtiene el contenido completo (cabeceras, cuerpo, adjuntos) de un correo específico usando su ID de secuencia.

• Gestión de etiquetas (CRUD):

  • Lista todas las etiquetas (carpetas) de Gmail disponibles.

  • Crea nuevas etiquetas personalizadas.

  • Renombra etiquetas personalizadas existentes.

  • Elimina etiquetas personalizadas existentes (no se pueden eliminar etiquetas del sistema).

  • Aplica etiquetas a correos individuales.

  • Quita etiquetas de correos individuales.

• Operaciones por lotes:

  • Aplica etiquetas a múltiples correos simultáneamente usando IDs de secuencia.

  • Quita etiquetas de múltiples correos simultáneamente.

  • Mueve múltiples correos a una etiqueta/carpeta específica.

• Envío de correos: Envía correos nuevos (requiere configuración SMTP).

• Reenvío de correos: Reenvía correos existentes, incluidos los adjuntos (requiere configuración SMTP).

• Recuento diario de correos: Cuenta los correos recibidos por día dentro de un rango de fechas especificado.

Related MCP server: Gmail MCP Server

Estructura del proyecto

.
├── .gitignore         # Specifies intentionally untracked files that Git should ignore
├── .python-version    # Specifies Python version (used by pyenv)
├── LICENSE            # Project license file
├── pyproject.toml     # Python project configuration (dependencies, build system)
├── README.md          # This file
├── task_list.md       # Tracks development progress
├── uv.lock            # Lock file for uv package manager
├── src/
│   └── email_client/
│       ├── __init__.py
│       ├── config.py        # Handles loading configuration from environment variables (.env)
│       ├── handlers.py      # Implements the logic for handling MCP tool calls
│       ├── imap_client.py   # Contains functions for interacting with IMAP server
│       ├── server.py        # Main MCP server script using @modelcontextprotocol/sdk
│       ├── smtp_client.py   # Contains functions for interacting with SMTP server
│       ├── tool_definitions.py # Defines the available MCP tools and their schemas
│       └── utils.py         # Utility functions (e.g., email parsing, date formatting)
└── ... (other potential files like test scripts, helper scripts)

Configuración

1. Clona el repositorio (si corresponde):

   git clone https://github.com/david-strejc/gmail-mcp-server.git
   cd gmail-mcp-server

2. Instala las dependencias: Este proyecto usa uv para la gestión de paquetes.

   # Ensure uv is installed (e.g., pip install uv)
   uv venv  # Create virtual environment (.venv)
   uv sync  # Install dependencies from pyproject.toml and uv.lock
   source .venv/bin/activate # Activate the virtual environment

   (Alternativamente, si no usas uv, crea un entorno virtual e instala con pip install -r requirements.txt si se genera un requirements.txt).

3. Configura las variables de entorno: Crea un archivo .env en el directorio raíz del proyecto y añade tus credenciales de Gmail y la configuración del servidor:

   # .env file
   GMAIL_EMAIL=your_email@gmail.com
   GMAIL_PASSWORD=your_app_password # Use an App Password if 2FA is enabled
   GMAIL_IMAP_SERVER=imap.gmail.com
   GMAIL_SMTP_SERVER=smtp.gmail.com
   GMAIL_SMTP_PORT=587 # Or 465 for SSL

   • Importante: Para Gmail, si tienes la verificación en dos pasos activada, debes generar y utilizar una "contraseña de aplicación". Las contraseñas normales no funcionarán. Consulta la documentación de Google sobre contraseñas de aplicaciones.

   • Asegúrate de que "Acceso de aplicaciones menos seguras" esté habilitado si no estás usando 2FA (esto generalmente no se recomienda).

Ejecutar el servidor MCP

Activa el entorno virtual y ejecuta el script del servidor:

source .venv/bin/activate
python src/email_client/server.py

El servidor se iniciará y escuchará solicitudes MCP a través de la entrada/salida estándar.

Integración con un cliente MCP (p. ej., Cline)

Añade la configuración del servidor al archivo de configuración de tu cliente MCP (p. ej., cline_mcp_settings.json o claude_desktop_config.json).

Ejemplo de entrada en cline_mcp_settings.json:

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/your/project/gmail-mcp-server/.venv/bin/python",
      "args": ["/path/to/your/project/gmail-mcp-server/src/email_client/server.py"],
      "env": {}, // Environment variables are loaded from .env by the script
      "enabled": true, // Set to true to enable
      "autoApprove": [] // Configure auto-approval if desired
    }
    // ... other servers
  }
}

• Reemplaza /path/to/your/project/gmail-mcp-server con la ruta absoluta real a este directorio del proyecto.

• Asegúrate de que command apunte al ejecutable de Python dentro del entorno virtual del proyecto (.venv/bin/python).

Una vez configurado y habilitado, el cliente debería conectarse al servidor y las herramientas definidas estarán disponibles.

Herramientas disponibles (resumen)

• search-emails: Busca correos.

• get-email-content: Obtiene los detalles completos de un correo.

• count-daily-emails: Cuenta los correos por día.

• list-labels: Lista todas las etiquetas/carpetas.

• create-label: Crea una nueva etiqueta.

• rename-label: Renombra una etiqueta existente.

• delete-label: Elimina una etiqueta.

• apply-label: Aplica una etiqueta a un correo.

• remove-label: Quita una etiqueta de un correo.

• apply-label-batch: Aplica una etiqueta a múltiples correos.

• remove-label-batch: Quita una etiqueta de múltiples correos.

• move-email: Mueve un solo correo a una etiqueta.

• move-email-batch: Mueve múltiples correos a una etiqueta.

• send-email: Envía un correo nuevo.

• forward-email: Reenvía un correo existente.

Consulta src/email_client/tool_definitions.py para ver los esquemas de entrada detallados de cada herramienta.