https://github.com/FranciscoYuster/claude-client-gmail-mcp
Acceso de asistentes de IA a Gmail mediante el Model Context Protocol (MCP)
https://github.com/FranciscoYuster/claude-client-gmail-mcp
Last synced: about 2 months ago
JSON representation
Acceso de asistentes de IA a Gmail mediante el Model Context Protocol (MCP)
- Host: GitHub
- URL: https://github.com/FranciscoYuster/claude-client-gmail-mcp
- Owner: FranciscoYuster
- License: mit
- Created: 2025-06-06T05:32:26.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2025-06-09T02:14:34.000Z (5 months ago)
- Last Synced: 2025-06-09T03:24:27.971Z (5 months ago)
- Language: Python
- Size: 22.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - **claude-client-gmail-mcp** - Acceso de asistentes de IA a Gmail mediante Model Context Protocol (MCP) `python` `mcp` `ai` `pip install git+https://github.com/FranciscoYuster/gmail-client-mcp-server` (AI/ML)
- awesome-mcp-servers - **claude-client-gmail-mcp** - Acceso de asistentes de IA a Gmail mediante Model Context Protocol (MCP) `python` `mcp` `ai` `pip install git+https://github.com/FranciscoYuster/gmail-client-mcp-server` (AI/ML)
README
# 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](https://www.anthropic.com/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](https://console.cloud.google.com/apis/credentials)
- 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!
2. 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
```
4. El instalador hará el resto
5. 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:
```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
```
4. El instalador hará el resto.
5. 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:
```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
```
4. Configura credenciales OAuth:
- Crea un directorio llamado `credentials` en la raíz del proyecto
- Crea un proyecto en [Google Cloud Console](https://console.cloud.google.com/)
- 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](LICENSE).