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

1. Clona el repositorio:

   git clone <URL_DEL_REPOSITORIO>
   cd gmail-mcp-server
   

2. Instala las dependencias del proyecto con uv:

   uv pip install -r uv.lock
   

Construcción y empaquetado

1. (Opcional) Instala la herramienta build:

   uv pip install build
   

2. 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:

1. Ve a la Google Cloud Console.
2. Crea un nuevo proyecto o selecciona uno existente.
3. Ve a "APIs y servicios" > "Biblioteca" y busca "Gmail API". Haz clic en "Habilitar".
4. Ve a "APIs y servicios" > "Credenciales" y haz clic en "Crear credenciales" > "ID de cliente de OAuth".
5. Selecciona "Aplicación de escritorio" como tipo de aplicación.
6. Asigna un nombre y haz clic en "Crear".
7. Descarga el archivo JSON, ábrelo y copia los valores de client_id y client_secret.
8. 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:

1. Abre tu archivo de configuración de shell (~/.bashrc, ~/.zshrc, etc.).
2. Añade la línea:

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

3. 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

• Guía oficial de empaquetado Python
• Documentación pyproject.toml
• Google API Python Client (Gmail)
• google-auth
• dotenv (python-dotenv)
• mcp[cli] (Model Context Protocol CLI)
• Model Context Protocol (MCP)

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.