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:

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.