Servidor MCP de Gmail | Awesome MCP Servers

Servidor MCP Gmail Mejorado

Un servidor de Protocolo de Contexto de Modelo (MCP) potente y completo para la integración con Gmail, escrito en Python. Este servidor permite que asistentes de IA como Claude interactúen con Gmail mediante lenguaje natural, ofreciendo capacidades integrales de gestión de correos electrónicos.

🌟 Características Clave

📧 Gestión Completa de Correos

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

📝 Gestión de Borradores

Crear borradores de correos para revisión posterior
Listar todos los borradores de correos
Editar borradores existentes

🏷️ Gestión Avanzada de Etiquetas

Listar todas las etiquetas disponibles
Crear etiquetas personalizadas
Aplicar/eliminar etiquetas de los correos
Renombrar etiquetas existentes
Eliminar etiquetas en desuso
Buscar correos por etiqueta

📁 Organización de Carpetas

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

🔍 Búsqueda y Filtrado Potentes

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

🗄️ Gestión de Archivo

Archivar correos (eliminar de la bandeja de entrada sin borrar)
Archivar por lotes múltiples correos que coincidan con criterios de búsqueda
Listar todos los correos archivados
Restaurar correos archivados a la bandeja de entrada

🚀 Comenzando

Requisitos Previos

Python 3.8+
Proyecto de Google Cloud con la API de Gmail habilitada
Credenciales 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 OAuth:
- Seleccionar tipo de usuario "Externo"
- Añadir tu correo como usuario de prueba
- Añadir el alcance: https://www.googleapis.com/auth/gmail/modify
Crear credenciales OAuth 2.0:
- Elegir "Aplicación de escritorio" como tipo de aplicación
- Descargar el archivo JSON de credenciales

Configuración

Almacena tus credenciales de forma segura y especifica 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

Ejecutar con Claude Desktop

Añade lo siguiente a tu archivo de configuración de Claude Desktop (generalmente 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"
      ]
    }
  }
}

Probar con MCP Inspector

Para pruebas y depuración, usa el MCP Inspector:

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 commits de credenciales o archivos de token en el control de versiones
Almacena las credenciales en una ubicación segura con permisos adecuados
El servidor solicitará confirmación del usuario antes de realizar acciones sensibles
Revisa la consola de Google Cloud periódicamente para detectar actividad inusual
Considera usar variables de entorno para rutas sensibles

🛠️ Arquitectura

Esta implementación presenta una arquitectura integral de un solo archivo que maneja todas las operaciones de Gmail a través de las bibliotecas cliente de la API de Google. Los componentes clave incluyen:

Autenticación OAuth2 con renovación automática de tokens
Manejo integral de errores y registro
Definiciones de herramientas estructuradas con esquemas de entrada claros
Análisis y formato eficientes de correos

📚 Ejemplos de Prompts

Prueba estos prompts con Claude después de conectar el servidor MCP de Gmail:

"Muéstrame mis correos no leídos"
"Busca correos de example@domain.com con archivos adjuntos"
"Crea una nueva etiqueta llamada 'Proyectos Importantes'"
"Redacta un correo a john@example.com sobre la próxima reunión"
"Archiva todos los correos de newsletter@example.com"
"Crea un filtro para etiquetar automáticamente los correos de mi equipo"

🤝 Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request).

Haz un fork del repositorio
Crea tu rama de características (git checkout -b feature/amazing-feature)
Realiza tus cambios (git commit -m 'Add some amazing feature')
Envía los cambios a la rama (git push origin feature/amazing-feature)
Abre una Solicitud de Extracción

📄 Licencia

Este proyecto está bajo la Licencia GPL-3.0: consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

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

Gmail

Documentación