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)
- Primero:
- Ve a Google Cloud Console
- Crea un proyecto y habilita la API de Gmail
- Agregahttp://localhost:8080/a las URIs de redireccionamiento autorizados
- Descarga el archivoclient_secret_...jsony 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! - Clona este repositorio desde tu terminal:```sh
git clone https://github.com/FranciscoYuster/claude-client-gmail-mcp
cd claude-client-gmail-mcp
3. Y ejecuta el script:```sh
python setup.py
- El instalador hará el resto
- Cuando veas el mensaje final, ¡abre Claude Desktop y disfruta!
💻 Instalación en macOS / Linux
- Sigue los mismos pasos de Google Cloud indicados arriba para obtener tu archivo de credenciales y dejarlo en Descargas.
- Clona este repositorio desde tu terminal:```sh
git clone https://github.com/FranciscoYuster/gmail-client-mcp-server
cd gmail-client-mcp-server
3. Ejecuta el script para sistemas Unix:```sh
python3 setupUnix.py
- El instalador hará el resto.
- 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
- Clona este repositorio:```sh
git clone https://github.com/FranciscoYuster/claude-client-gmail-mcp
cd claude-client-gmail-mcp
2. Crea y activa un entorno virtual:```sh
uv init
# o alternativamente
uv venv
Luego actívalo:```sh
.venv\scripts\activate
3. Instala dependencias:```sh
uv pip install -r requirements.txt
- Configura credenciales OAuth:
- Crea un directorio llamadocredentialsen 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.
5. 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:```json
{
"mcpServers": {
"gmail-mcp": {
"command": "uv",
"args": [
"--directory",
"/path/to/your/gmail-mcp/src",
"run",
"main.py"
]
}
}
}
6. 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.
