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