Gmail Client MCP Server

Gmail MCP - Instalación Automática y Segura

Acceso de asistentes de IA a Gmail mediante el Model Context Protocol (MCP)

Requisito esencial: Debes tener instalado Claude Desktop para poder utilizar este servidor MCP.

🧪 ¿Qué es MCP?

MCP (Model Context Protocol) es un protocolo de integración desarrollado por Antrophic para facilitar la comunicación entre modelos de lenguaje (como ChatGPT o Claude) y herramientas externas (APIs, bases de datos, servicios web, etc.). Su objetivo es proporcionar un contexto ampliado, estructurado y en tiempo real a los modelos, permitiéndoles ejecutar acciones más allá del texto.

🎥 Video con ejemplo de uso

https://github.com/user-attachments/assets/e49b2d76-bcef-4d44-9222-6818f0f57998

🚀 Instalación rápida (Windows)

1. Primero:

- Ve a Google Cloud Console - Crea un proyecto y habilita la API de Gmail - Agrega http://localhost:8080/ a las URIs de redireccionamiento autorizados - Descarga el archivo client_secret_...json y déjalo en tu carpeta Descargas (no te preocupes por el nombre ni la ubicación final) - El instalador detectará y moverá el archivo automáticamente a la carpeta correcta y con el nombre adecuado

[!IMPORTANT] Solo necesitas descargar el archivo de credenciales desde Google Cloud despues configurar las URIs de redireccionamiento autorizadas y dejarlo en Descargas. ¡No te preocupes por el nombre ni la ubicación final, el instalador se encarga de todo!

1. Clona este repositorio desde tu terminal:

   git clone https://github.com/FranciscoYuster/claude-client-gmail-mcp
   cd claude-client-gmail-mcp

1. Y ejecuta el script:

   python setup.py

1. El instalador hará el resto
2. Cuando veas el mensaje final, ¡abre Claude Desktop y disfruta!

💻 Instalación en macOS / Linux

1. Sigue los mismos pasos de Google Cloud indicados arriba para obtener tu archivo de credenciales y dejarlo en Descargas.
2. Clona este repositorio desde tu terminal:

   git clone https://github.com/FranciscoYuster/gmail-client-mcp-server
   cd gmail-client-mcp-server

1. Ejecuta el script para sistemas Unix:

   python3 setupUnix.py

1. El instalador hará el resto.
2. Cuando veas el mensaje final, ¡abre Claude Desktop y disfruta!

[!IMPORTANT] Si usas Windows, ejecuta: python setup.py Si usas macOS o Linux, ejecuta: python3 setupUnix.py Ambos scripts ejecutan la instalación, pero cada uno está adaptado a su sistema operativo.

🔒 Seguridad

[!WARNING] Nunca subas ni compartas tu archivo de credenciales. Si lo expones por error, elimínalo y genera uno nuevo en Google Cloud Console. El script nunca sube ni distribuye tus datos sensibles.

📝 Requisitos previos

• Python 3.11 o superior
• git
• Cuenta de Gmail
• Claude Dekstop

[!TIP] El instalador te guiará para instalar cualquier requisito que falte.

⚙️ Configuración manual

🚀 Configuración

1. Clona este repositorio:

   git clone https://github.com/FranciscoYuster/claude-client-gmail-mcp
   cd claude-client-gmail-mcp

1. Crea y activa un entorno virtual:

   uv init
   # o alternativamente
   uv venv

Luego actívalo:

   .venv\scripts\activate

1. Instala dependencias:

   uv pip install -r requirements.txt

1. Configura credenciales OAuth:

- Crea un directorio llamado credentials en la raíz del proyecto - Crea un proyecto en Google Cloud Console - Habilita la API de Gmail - Crea credenciales OAuth - Agrega la siguiente URI a las URIs de redirección autorizadas:

     http://localhost:8080/

- Descarga el archivo JSON de credenciales y guárdalo como credentials/client_secret_gmail_oauth.json

[!CAUTION] Asegúrate de que la ruta y el nombre del archivo de credenciales sean correctos para evitar errores de autenticación.

1. Agrega el servidor MCP a tu configuración JSON. Por favor, consulta la documentación oficial de tu cliente MCP para instrucciones específicas. Asegúrate de ajustar la ruta según tu entorno:

   {
       "mcpServers": {
           "gmail-mcp": {
               "command": "uv",
               "args": [
                   "--directory",
                   "/path/to/your/gmail-mcp/src",
                   "run",
                   "main.py"
               ]
           }
       }
   }

1. Ejecuta Claude Desktop

Herramientas disponibles

El servidor incluye una serie de herramientas para operar y automatizar Gmail desde asistentes de IA. Estas herramientas permiten enviar, leer, buscar, gestionar correos y etiquetas. A continuación se listan las principales funciones disponibles:

Operaciones de correo electrónico

• Enviar correos (con adjuntos, CC, BCC, respuesta a hilos)
• Crear borradores de correos (con adjuntos)
• Descargar adjuntos de un mensaje
• Leer correos por ID (texto y HTML, con fragmentación para mensajes grandes)
• Buscar correos con filtros avanzados (consulta, etiquetas, remitente, adjuntos, paginación)
• Obtener hilos completos de conversación
• Marcar como leído/no leído/importante/no importante

Gestión de etiquetas

• Añadir o eliminar etiquetas de un correo
• Crear nuevas etiquetas
• Eliminar etiquetas por nombre
• Listar todas las etiquetas
• Obtener o crear etiquetas por nombre
• Actualizar configuración de etiquetas (nombre, visibilidad, color)
• Buscar etiquetas por nombre

Estas herramientas permiten una gestión avanzada y automatizada del correo electrónico y las etiquetas de Gmail, facilitando la integración con asistentes de IA y flujos de trabajo

📝 Licencia

MIT. Consulta el archivo LICENSE.