Servidor MCP de Gmail mejorado

Un potente servidor de Protocolo de Contexto de Modelo (MCP) con numerosas funciones para la integración de Gmail, escrito en Python. Este servidor permite a asistentes de IA como Claude interactuar con Gmail mediante lenguaje natural, ofreciendo funciones integrales de gestión de correo electrónico.

🌟 Características principales

📧 Gestión completa del correo electrónico

Envíe correos electrónicos con asunto, contenido y destinatarios personalizables
Leer y recuperar contenido de correo electrónico con metadatos completos
Mover correos electrónicos a la papelera con confirmación
Marcar correos electrónicos como leídos/no leídos
Abrir correos electrónicos directamente en el navegador

📝 Gestión de Borradores

Crear borradores de correos electrónicos para revisarlos más tarde
Listar todos los borradores de correos electrónicos
Editar borradores existentes

🏷️ Gestión avanzada de etiquetas

Listar todas las etiquetas disponibles
Crear etiquetas personalizadas
Aplicar o eliminar etiquetas de los correos electrónicos
Cambiar el nombre de las etiquetas existentes
Eliminar etiquetas no utilizadas
Buscar correos electrónicos por etiqueta

📁 Organización de carpetas

Crear nuevas carpetas (implementadas como etiquetas de Gmail)
Mover correos electrónicos entre carpetas
Listar todas las carpetas disponibles

🔍 Búsqueda y filtrado potentes

Buscar correos electrónicos usando la sintaxis de consulta avanzada de Gmail
Crear, administrar y eliminar filtros de correo electrónico
Filtrar por remitente, destinatario, asunto, contenido y más
Personalice los resultados de búsqueda con parámetros flexibles

🗄️ Gestión de archivos

Archivar correos electrónicos (eliminarlos de la bandeja de entrada sin borrarlos)
Archivar por lotes varios correos electrónicos que coincidan con los criterios de búsqueda
Listar todos los correos electrónicos archivados
Restaurar correos electrónicos archivados en la bandeja de entrada

🚀 Primeros pasos

Prerrequisitos

Python 3.8+
Proyecto de Google Cloud con la API de Gmail habilitada
Credenciales de OAuth 2.0

Instalación

# Clone the repository
git clone https://github.com/theposch/gmail-mcp.git
cd gmail-mcp

# Set up a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
pip install -e .

Configuración de Google Cloud

Crear un nuevo proyecto de Google Cloud
Habilitar la API de Gmail
Configurar la pantalla de consentimiento de OAuth :
- Seleccione el tipo de usuario "Externo"
- Añade tu correo electrónico como usuario de prueba
- Agregue el alcance: https://www.googleapis.com/auth/gmail/modify
Crear credenciales OAuth 2.0 :
- Elija "Aplicación de escritorio" como tipo de aplicación
- Descargar el archivo de credenciales JSON

Configuración

Almacene sus credenciales de forma segura y especifique su ubicación al ejecutar el servidor:

# Example directory structure for credentials
mkdir -p ~/.gmail-mcp
# Move your downloaded credentials file
mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

🔧 Uso

Ejecutando con Claude Desktop

Agregue lo siguiente a su archivo de configuración de Claude Desktop (normalmente en ~/Library/Application Support/Claude/claude_desktop_config.json ):

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/gmail-mcp",
        "run",
        "gmail",
        "--creds-file-path",
        "/absolute/path/to/credentials.json",
        "--token-path",
        "/absolute/path/to/tokens.json"
      ]
    }
  }
}

Pruebas con MCP Inspector

Para realizar pruebas y depuraciones, utilice el Inspector MCP:

npx @modelcontextprotocol/inspector uv run /path/to/gmail-mcp/src/gmail/server.py --creds-file-path /path/to/credentials.json --token-path /path/to/tokens.json

🔐 Consideraciones de seguridad

Nunca envíe credenciales o archivos de token al control de versiones
Guarde las credenciales en una ubicación segura con los permisos adecuados
El servidor solicitará confirmación del usuario antes de realizar acciones sensibles
Revise Google Cloud Console periódicamente para detectar actividad inusual.
Considere usar variables de entorno para rutas sensibles

🛠️ Arquitectura

Esta implementación cuenta con una arquitectura integral de archivo único que gestiona todas las operaciones de Gmail mediante las bibliotecas cliente de la API de Google. Los componentes clave incluyen:

Autenticación OAuth2 con actualización automática de token
Manejo y registro de errores integral
Definiciones de herramientas estructuradas con esquemas de entrada claros
Análisis y formato de correo electrónico eficientes

📚 Ejemplos de indicaciones

Pruebe estas indicaciones con Claude después de conectarse al servidor MCP de Gmail:

"Muéstrame mis correos electrónicos no leídos"
Buscar correos electrónicos de ejemplo@dominio.com con archivos adjuntos
"Crear una nueva etiqueta llamada 'Proyectos importantes'"
Redactar un correo electrónico a john@example.com sobre la próxima reunión.
Archivar todos los correos electrónicos de newsletter@example.com
"Crear un filtro para etiquetar automáticamente los correos electrónicos de mi equipo"

🤝 Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Bifurcar el repositorio
Crea tu rama de funciones ( git checkout -b feature/amazing-feature )
Confirme sus cambios ( git commit -m 'Add some amazing feature' )
Empujar a la rama ( git push origin feature/amazing-feature )
Abrir una solicitud de extracción

📄 Licencia

Este proyecto está licenciado bajo la licencia GPL-3.0 - consulte el archivo de LICENCIA para obtener más detalles.

🙏 Agradecimientos

Inspirado en varias implementaciones de servidores MCP en la comunidad
Construido con el marco del Protocolo de Contexto de Modelo
Utiliza las bibliotecas de cliente API oficiales de Google

Enhanced Gmail MCP Server

Integrations