Gmail MCP Server

Servidor MCP de Gmail

Un servidor del Protocolo de Contexto de Modelos (MCP) para la integración de Gmail y Google Calendar con Claude Desktop, que permite interacciones inteligentes y conscientes del contexto con tu correo electrónico.

🌟 Características

• Análisis profundo de correos: Proporciona contexto completo de hilos de conversación enteros
• Respuestas conscientes del contexto: Genera respuestas considerando el historial completo de comunicaciones
• Sugerencias de acciones inteligentes: Analiza el contenido del correo para detectar eventos de calendario, tareas y seguimientos
• Integración con Calendar: Detecta eventos en correos y crea entradas de calendario con soporte de lenguaje natural
• Búsqueda avanzada: Busca en todo el historial de correos con comprensión semántica
• Personalización: Se adapta a tu estilo de comunicación con contactos específicos

🚀 Comenzando

Requisitos previos

• Python 3.10+
• Una cuenta de Google Cloud Platform con la API de Gmail y la API de Google Calendar (opcional) habilitadas
• Credenciales OAuth 2.0 para la API de Gmail y la API de Google Calendar (opcional)
• Claude Desktop con soporte MCP (actualmente la única interfaz LLM que soporta MCP)

Instalación

Instalación mediante Smithery

Para instalar automáticamente el Servidor de Integración de Gmail para Claude Desktop mediante Smithery:

npx -y @smithery/cli install @bastienchabal/gmail-mcp --client claude

Instalación manual

1. Clona este repositorio:

   git clone https://github.com/bastienchabal/gmail-mcp.git
   cd gmail-mcp
   

2. Configura un entorno virtual usando uv:

   pip install uv
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Instala las dependencias:

   uv pip install -e .
   

⚙️ Configuración

Paso 1: Autenticarse con Google

1. Ve a la Consola de Google Cloud
2. Crea un nuevo proyecto o selecciona uno existente
3. Habilita las APIs de Google:
   • Habilita la API de Gmail
   • Habilita la API de Calendar
4. Configura la pantalla de consentimiento de OAuth:
   • Selecciona el tipo de usuario "Externo"
   • Añade tu correo como usuario de prueba
   • Añade todos los ámbitos de Gmail y Calendar
5. Crea credenciales OAuth 2.0:
   • Elige "Aplicación de escritorio" como tipo de aplicación
   • Descarga el archivo de credenciales JSON y copia el ID de cliente y el Secreto de cliente

Paso 2: Configurar Claude Desktop

1. Crea o edita el archivo claude_desktop_config.json en /Users/<username>/Library/Application Support/Claude
2. Añade la siguiente configuración, reemplazando los marcadores de posición con tus valores reales:

{
  "mcpServers": {
    "gmail-mcp": {
      "command": "/<absolute-path>/gmail-mcp/.venv/bin/mcp",
      "args": [
        "run",
        "/<absolute-path>/gmail-mcp/gmail_mcp/main.py:mcp"
      ],
      "cwd": "/<absolute-path>/gmail-mcp",
      "env": {
        "PYTHONPATH": "/<absolute-path>/gmail-mcp",
        "CONFIG_FILE_PATH": "/<absolute-path>/gmail-mcp/config.yaml",
        "GOOGLE_CLIENT_ID": "<your-client-id>",
        "GOOGLE_CLIENT_SECRET": "<your-client-secret>",
        "TOKEN_ENCRYPTION_KEY": "<generate-a-random-key>"
      }
    }
  }
}

Notas:

• Reemplaza <absolute-path> con la ruta real a tu directorio gmail-mcp
• Reemplaza <your-client-id> y <your-client-secret> con tus credenciales OAuth de Google (generadas previamente en el archivo json)
• Opcional: Genera una clave de cifrado aleatoria con: python -c "import os; from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

La configuración está diseñada para mantener los datos sensibles (ID de cliente, secreto de cliente y clave de cifrado) en el archivo de configuración de Claude Desktop, mientras que los ajustes no sensibles se almacenan en el archivo config.yaml incluido en el repositorio.

Paso 3: Usar Claude Desktop

1. Abre Claude Desktop
2. Escribe un aviso como: "Por favor, recupera mi último correo"
3. Claude debería conectarse automáticamente al servidor MCP y pedirte que te autentiques con tu cuenta de Gmail (creando el archivo tokens.json)

❓ Solución de problemas

Nota importante sobre MCP

Si Claude Desktop no se conecta automáticamente (es decir, no ves el icono de la herramienta debajo del campo de entrada), puedes intentar:

• Reiniciar Claude Desktop
• Pedir a Claude que "Use el servidor Gmail MCP"
• Iniciar sesión en Gmail manualmente usando uno de estos métodos:

Nota importante sobre la autenticación

1. Problemas de autenticación:

   • Ejecuta python debug/auth_test.py para probar el proceso de autenticación con comentarios detallados
   • Comprueba que el archivo de token existe en la raíz del proyecto
   • Verifica que tu proyecto de Google Cloud Console tenga configurada la URI de redirección correcta
   • Asegúrate de que todos los ámbitos necesarios estén añadidos a tu pantalla de consentimiento de OAuth
   • Si ves errores de "El ámbito ha cambiado", asegúrate de que el ámbito openid esté incluido en tu pantalla de consentimiento de OAuth
   • Si ves errores de "redirect_uri_mismatch", añade la URI exacta que se muestra en el mensaje de error a tus URI de redirección autorizadas en Google Cloud Console
   • Si la página de devolución de llamada no carga o se procesa correctamente, comprueba si el puerto 8000 ya está en uso por otra aplicación

2. Problemas con la API de Calendar:

   • Asegúrate de haber habilitado la API de Calendar en Google Cloud Console
   • Comprueba que has otorgado todos los ámbitos necesarios durante la autenticación
   • Ejecuta python debug/reauth_calendar.py para volver a autenticarte con los ámbitos de la API de Calendar
   • Verifica que CALENDAR_API_ENABLED esté configurado como true en tus variables de entorno

Nota importante sobre la integración con Calendar

La integración con Calendar se puede desactivar en el archivo de configuración. Si te has autenticado previamente con el servidor Gmail MCP y ahora estás habilitando la integración con Calendar, necesitarás volver a autenticarte para otorgar los ámbitos adicionales de la API de Calendar. Puedes hacerlo de la siguiente manera:

1. Elimina el archivo tokens.json existente (si está presente, ya sea en la raíz del proyecto o en ~/Users/<username/>gmail_mcp_tokens/tokens.json)
2. Reinicia el servidor MCP
3. Sigue el proceso de autenticación nuevamente

👤 Uso

El MCP de Gmail proporciona herramientas potentes y conscientes del contexto para gestionar tus correos y tu calendario:

Gestión de correos

• Resumen de correos: Obtén una vista completa de tu bandeja de entrada con recuentos y correos recientes
• Búsqueda avanzada: Usa la sintaxis de búsqueda avanzada de Gmail para encontrar correos específicos
• Análisis detallado de correos: Visualiza correos con contexto completo, incluido el historial del hilo y la información del remitente

Respuestas de correo conscientes del contexto

• Preparación inteligente de respuestas: Analiza el contexto completo de un hilo de correo antes de responder
• Análisis de patrones de comunicación: Comprende tu historial de comunicación con el remitente
• Redacción personalizada: Crea respuestas preliminares que coincidan con tu estilo de comunicación con contactos específicos
• Reconocimiento de entidades: Identifica fechas, horas, elementos de acción y otras entidades importantes en los correos
• Contexto de correos relacionados: Considera otros correos relevantes al redactar respuestas

Integración con Calendar

• Creación de eventos: Crea eventos de calendario con descripciones de tiempo en lenguaje natural
• Detección de eventos: Detecta automáticamente eventos potenciales mencionados en los correos
• Gestión del calendario: Ve, busca y gestiona tus próximos eventos de calendario
• Programación inteligente: Programa reuniones con el contexto adecuado de las conversaciones de correo

Solicitudes de ejemplo

Puedes pedir a Claude que use estas capacidades con solicitudes en lenguaje natural como:

• "Muéstrame un resumen de mi bandeja de entrada"
• "Encuentra todos los correos no leídos de mi jefe sobre el informe trimestral"
• "Ayúdame a responder al último correo de Sarah sobre la fecha límite del proyecto"
• "Crea un evento de calendario para la reunión de equipo mencionada en el correo de John"
• "¿Qué reuniones tengo programadas para la próxima semana?"
• "Analiza este hilo de correo y ayúdame a entender los puntos clave antes de responder"
• "Redacta una respuesta a este correo considerando mis comunicaciones previas con esta persona"

Recursos disponibles

El MCP proporciona recursos contextuales enriquecidos que Claude puede acceder:

• Contexto del correo: Información detallada sobre correos específicos
• Contexto del hilo: Historial completo de conversaciones para hilos de correo
• Contexto del remitente: Información sobre tu relación e historial de comunicación con los remitentes
• Estado de autenticación: Estado actual de autenticación con Google
• Estado de Gmail: Resumen de tu cuenta de Gmail
• Información del servidor: Detalles sobre la configuración del servidor MCP

Guías disponibles

El MCP incluye varias guías para ayudarte a aprovechar al máximo sus capacidades:

• Guía de inicio rápido: Instrucciones básicas para comenzar
• Guía de autenticación: Ayuda con el proceso de autenticación
• Guía de búsqueda: Referencia de la sintaxis avanzada de búsqueda de Gmail
• Guía de respuestas: Mejores prácticas para respuestas de correo conscientes del contexto
• Guía de depuración: Solución de problemas comunes

☑️ Este MCP está configurado para que Claude siempre te pida confirmación antes de realizar cualquier acción importante, como enviar un correo o crear una reunión.

⚠ Aviso de beta

Este MCP está en desarrollo y actualmente se encuentra en beta.

📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT.

💡 Agradecimientos

• Este proyecto utiliza el Protocolo de Contexto de Modelos (MCP) desarrollado por Anthropic
• El acceso a la API de Gmail lo proporcionan los servicios de API de Google