README - gmail-mcp-server by ivanlhz

gmail-mcp-server

Repositorio oficial: https://github.com/ivanlhz/gmail-mcp-server

Servidor para exponer la API de Gmail mediante el Model Context Protocol (MCP), diseñado para su integración con LLMs y uso en entornos como Claude Desktop.

Descripción

Este proyecto permite exponer la API de Gmail vía MCP, facilitando su integración con LLMs y uso en entornos como Claude Desktop.

Tools MCP disponibles

El servidor expone las siguientes tools MCP para interactuar con Gmail:

Tool	Descripción
`get_labels()`	Obtiene todas las etiquetas del usuario Gmail.
`get_label_by_id(label_id)`	Obtiene los datos de una etiqueta específica a partir de su ID.
`create_label(name, bg_color, text_color)`	Crea una nueva etiqueta en Gmail con nombre y colores opcionales.
`update_label(label_id, name, bg_color, text_color)`	Actualiza una etiqueta existente.
`delete_label(label_id)`	Elimina una etiqueta de Gmail a partir de su ID.
`mark_emails_as_read(emails_ids: List[str])`	Marca como leídos los emails cuyo ID se pase en la lista.
`mark_emails_as_unread(emails_ids: List[str])`	Marca como no leídos los emails cuyo ID se pase en la lista.
`add_labels(emails_ids: List[str], labels: List[str])`	Asigna una o varias etiquetas a todos los emails indicados en la lista de IDs.
`get_all_emails_ids_by_query(query: str, max_results: int, next_page_token: str = None)`	Devuelve una lista paginada de IDs de emails según la consulta de Gmail. Usa `next_page_token` para paginar.
`get_email_detail(email_id: str)`	Devuelve los detalles completos de un email específico por su ID.

Estructura del proyecto

.
├── src/
│   ├── gmail/                   # Lógica de integración con Gmail
│   │   ├── __init__.py
│   │   ├── auth.py              # Autenticación y OAuth
│   │   ├── service.py           # Lógica de negocio (mensajes, etiquetas)
│   │   └── models/
│   │       └── label_model.py   # Modelos de etiquetas de Gmail
│   ├── gmail_mcp_server/
│   │   ├── __init__.py
│   │   └── main.py              # Punto de entrada MCP y definición de tools
│   └── gmail_mcp_server.egg-info/ # Info de empaquetado
├── pyproject.toml               # Configuración del paquete y dependencias
├── uv.lock                      # Lockfile de dependencias (usado por uv)
├── README.md                    # Este archivo
├── LICENSE                      # Licencia MIT
└── .venv/                       # Entorno virtual (no versionar)

Requisitos

Python 3.11 o superior
uv (para la gestión de dependencias y entornos)
build (solo si quieres empaquetar el módulo)
Claude Desktop (si se va a usar allí)

Instalación de dependencias

Clona el repositorio:

git clone <URL_DEL_REPOSITORIO>
cd gmail-mcp-server

Instala las dependencias del proyecto con uv:
```
uv pip install -r uv.lock
```

Construcción y empaquetado

(Opcional) Instala la herramienta build:
```
uv pip install build
```
Empaqueta el módulo:
```
uv run -m build
```
Esto generará archivos .whl y .tar.gz en el directorio dist/.

Instalación local del paquete

Instala el paquete en tu entorno:

uv pip install dist/gmail_mcp_server-0.1.1-py3-none-any.whl

(Asegúrate de ajustar el nombre del archivo .whl si cambia la versión.)

Gestión de dependencias con uv

Este proyecto utiliza uv para gestionar las dependencias y los entornos virtuales.

Instalar todas las dependencias del proyecto:
```
uv pip install -r uv.lock
```

Instalar nuevas dependencias:

uv pip install <paquete>
uv pip freeze > uv.lock

Consulta la documentación oficial de uv para más detalles.

Obtener credenciales de Google (GOOGLE_CLIENT_ID y SECRET)

Para que el servidor pueda acceder a la API de Gmail, necesitas crear credenciales OAuth 2.0 en Google Cloud:

Ve a la Google Cloud Console.
Crea un nuevo proyecto o selecciona uno existente.
Ve a "APIs y servicios" > "Biblioteca" y busca "Gmail API". Haz clic en "Habilitar".
Ve a "APIs y servicios" > "Credenciales" y haz clic en "Crear credenciales" > "ID de cliente de OAuth".
Selecciona "Aplicación de escritorio" como tipo de aplicación.
Asigna un nombre y haz clic en "Crear".
Descarga el archivo JSON, ábrelo y copia los valores de client_id y client_secret.
Usa estos valores como variables de entorno GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET al lanzar el servidor.

Más información en la guía oficial de Google.

Integración con Claude Desktop y otros clientes MCP

Windows

El ejecutable se encuentra en:

C:\Users\<usuario>\develop\proyectos\mcp\gmail-mcp-server\.venv\Scripts\gmail-mcp-server.exe

Puedes ejecutarlo directamente desde esa ruta o añadir .venv\Scripts\ al PATH para poder usar gmail-mcp-server desde cualquier terminal.
Si has añadido la carpeta de scripts al PATH (recomendado): Ahora puedes usar simplemente gmail-mcp-server como comando global en cualquier terminal.

Recomendación para Claude Desktop: En tu configuración (por ejemplo, claude.config.json):

Si NO tienes el PATH configurado:

{
  "mcpServers": {
    "gmail": {
      "command": "C:\\Users\\<usuario>\\develop\\proyectos\\mcp\\gmail-mcp-server\\.venv\\Scripts\\gmail-mcp-server.exe",
      "env": {
        "GOOGLE_CLIENT_ID": "TU_ID",
        "GOOGLE_CLIENT_SECRET": "TU_SECRET"
      }
    }
  }
}

Si SÍ tienes el PATH configurado:

{
  "mcpServers": {
    "gmail": {
      "command": "gmail-mcp-server",
      "env": {
        "GOOGLE_CLIENT_ID": "TU_ID",
        "GOOGLE_CLIENT_SECRET": "TU_SECRET"
      }
    }
  }
}

Cambia <usuario> por tu nombre de usuario de Windows y completa tus credenciales.

Mac/Linux

El ejecutable se encuentra en:

/ruta/a/tu/proyecto/.venv/bin/gmail-mcp-server

Puedes ejecutarlo directamente desde esa ruta.

Para agregar el ejecutable al PATH de forma permanente:

Abre tu archivo de configuración de shell (~/.bashrc, ~/.zshrc, etc.).

Añade la línea:

export PATH="/ruta/a/tu/proyecto/.venv/bin:$PATH"

Guarda el archivo y ejecuta source ~/.bashrc o source ~/.zshrc (según tu shell), o reinicia la terminal.

Ahora podrás usar simplemente gmail-mcp-server como comando global.

Recomendación para Claude Desktop:

Si NO tienes el PATH configurado:

{
  "mcpServers": {
    "gmail": {
      "command": "/ruta/a/tu/proyecto/.venv/bin/gmail-mcp-server",
      "env": {
        "GOOGLE_CLIENT_ID": "TU_ID",
        "GOOGLE_CLIENT_SECRET": "TU_SECRET"
      }
    }
  }
}

Si SÍ tienes el PATH configurado:

{
  "mcpServers": {
    "gmail": {
      "command": "gmail-mcp-server",
      "env": {
        "GOOGLE_CLIENT_ID": "TU_ID",
        "GOOGLE_CLIENT_SECRET": "TU_SECRET"
      }
    }
  }
}

Cambia /ruta/a/tu/proyecto/ por la ruta real y completa tus credenciales.
Tras cualquier cambio, reinicia Claude Desktop para que detecte y ejecute el servidor MCP correctamente.

Referencias

Comunidad y contribución

¿Tienes dudas, sugerencias o encontraste un bug? Abre un issue.
¿Quieres contribuir? Haz un fork y envía tu pull request. ¡Las contribuciones son bienvenidas!
Para cualquier consulta, también puedes abrir una discusión en la pestaña Discussions del repositorio.