MCP Headless Gmail Server

Un servidor sin interfaz gráfica para obtener y enviar correos electrónicos a través de la API de Gmail, que requiere credenciales de la API de Google en tiempo de ejecución.

GitHub
55
Prueba este MCPPatrocinado

Documentación

MCP Headless Gmail Server (NPM & Docker)

npm version Docker Pulls License: MIT

Un servidor MCP (Model Context Protocol) que permite obtener y enviar correos de Gmail sin necesidad de configurar credenciales o tokens locales.

Headless Gmail Server MCP server

¿Por qué MCP Headless Gmail Server?

Ventajas críticas

  • Operación headless y remota: A diferencia de otras soluciones MCP de Gmail que requieren ejecutarse fuera de Docker y acceso a archivos locales, este servidor puede ejecutarse completamente headless en entornos remotos sin navegador ni acceso a archivos locales.
  • Arquitectura desacoplada: Cualquier cliente puede completar el flujo OAuth de forma independiente y luego pasar las credenciales como contexto a este servidor MCP, creando una separación completa entre el almacenamiento de credenciales y la implementación del servidor.

Conveniente pero no crítico

  • Funcionalidad enfocada: En muchos casos de uso, especialmente en aplicaciones de marketing, solo se necesita acceso a Gmail sin servicios adicionales de Google como Calendar, lo que hace que esta implementación enfocada sea ideal.
  • Listo para Docker: Diseñado pensando en la contenedorización para una configuración bien aislada, independiente del entorno y de un solo clic.
  • Dependencias confiables: Construido sobre la biblioteca google-api-python-client, bien mantenida.

Características

  • Obtener los correos más recientes de Gmail con los primeros 1k caracteres del cuerpo
  • Obtener el contenido completo del cuerpo del correo en fragmentos de 1k usando el parámetro offset
  • Enviar correos a través de Gmail
  • Renovar los tokens de acceso por separado
  • Manejo automático de renovación de tokens

Requisitos previos

  • Python 3.10 o superior
  • Credenciales de la API de Google (ID de cliente, secreto de cliente, token de acceso y token de renovación)

Instalación

# Clone the repository
git clone https://github.com/baryhuang/mcp-headless-gmail.git
cd mcp-headless-gmail

# Install dependencies
pip install -e .

Docker

Construyendo la imagen Docker

# Build the Docker image
docker build -t mcp-headless-gmail .

Uso con Claude Desktop

Puedes configurar Claude Desktop para usar la imagen Docker añadiendo lo siguiente a tu configuración de Claude:

docker

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "buryhuang/mcp-headless-gmail:latest"
      ]
    }
  }
}

npm version

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@peakmojo/mcp-server-headless-gmail"
      ]
    }
  }
}

Nota: Con esta configuración, deberás proporcionar tus credenciales de la API de Google en las llamadas a las herramientas como se muestra en la sección Uso de las herramientas. Las credenciales de Gmail no se pasan como variables de entorno para mantener la separación entre el almacenamiento de credenciales y la implementación del servidor.

Publicación multiplataforma

Para publicar la imagen Docker para múltiples plataformas, puedes usar el comando docker buildx. Sigue estos pasos:

  1. Crea una nueva instancia de builder (si aún no lo has hecho):

    docker buildx create --use

  2. Construye y sube la imagen para múltiples plataformas:

    docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-headless-gmail:latest --push .

  3. Verifica que la imagen esté disponible para las plataformas especificadas:

    docker buildx imagetools inspect buryhuang/mcp-headless-gmail:latest

Uso

El servidor proporciona funcionalidad de Gmail a través de herramientas MCP. El manejo de autenticación se simplifica con una herramienta dedicada de renovación de tokens.

Iniciando el servidor

mcp-server-headless-gmail

Usando las herramientas

Al usar un cliente MCP como Claude, tienes dos formas principales de manejar la autenticación:

Renovando tokens (primer paso o cuando los tokens expiran)

Si tienes tanto el token de acceso como el de renovación:

{
  "google_access_token": "your_access_token",
  "google_refresh_token": "your_refresh_token",
  "google_client_id": "your_client_id",
  "google_client_secret": "your_client_secret"
}

Si tu token de acceso ha expirado, puedes renovarlo solo con el token de renovación:

{
  "google_refresh_token": "your_refresh_token",
  "google_client_id": "your_client_id",
  "google_client_secret": "your_client_secret"
}

Esto devolverá un nuevo token de acceso y su tiempo de expiración, que podrás usar para llamadas posteriores.

Obteniendo correos recientes

Recupera los correos recientes con los primeros 1k caracteres del cuerpo de cada correo:

{
  "google_access_token": "your_access_token",
  "max_results": 5,
  "unread_only": false
}

La respuesta incluye:

  • Metadatos del correo (id, threadId, from, to, subject, date, etc.)
  • Los primeros 1000 caracteres del cuerpo del correo
  • body_size_bytes: Tamaño total del cuerpo del correo en bytes
  • contains_full_body: Booleano que indica si el cuerpo completo está incluido (true) o truncado (false)

Obteniendo el contenido completo del cuerpo del correo

Para correos con cuerpos de más de 1k caracteres, puedes recuperar el contenido completo en fragmentos:

{
  "google_access_token": "your_access_token",
  "message_id": "message_id_from_get_recent_emails",
  "offset": 0
}

También puedes obtener el contenido del correo por ID de hilo:

{
  "google_access_token": "your_access_token",
  "thread_id": "thread_id_from_get_recent_emails",
  "offset": 1000
}

La respuesta incluye:

  • Un fragmento de 1k del cuerpo del correo a partir del offset especificado
  • body_size_bytes: Tamaño total del cuerpo del correo
  • chunk_size: Tamaño del fragmento devuelto
  • contains_full_body: Booleano que indica si el fragmento contiene el resto del cuerpo

Para recuperar el cuerpo completo de un correo largo, haz llamadas secuenciales aumentando el offset en 1000 cada vez hasta que contains_full_body sea true.

Enviando un correo

{
  "google_access_token": "your_access_token",
  "to": "recipient@example.com",
  "subject": "Hello from MCP Gmail",
  "body": "This is a test email sent via MCP Gmail server",
  "html_body": "<p>This is a <strong>test email</strong> sent via MCP Gmail server</p>"
}

Flujo de renovación de tokens

  1. Comienza llamando a la herramienta gmail_refresh_token con:
    • Tus credenciales completas (token de acceso, token de renovación, ID de cliente y secreto de cliente), o
    • Solo tu token de renovación, ID de cliente y secreto de cliente si el token de acceso ha expirado
  2. Usa el nuevo token de acceso devuelto para llamadas API posteriores.
  3. Si recibes una respuesta que indica expiración del token, llama nuevamente a la herramienta gmail_refresh_token para obtener un nuevo token.

Este enfoque simplifica la mayoría de las llamadas API al no requerir credenciales de cliente para cada operación, mientras que aún permite la renovación de tokens cuando sea necesario.

Obtención de credenciales de la API de Google

Para obtener las credenciales requeridas de la API de Google, sigue estos pasos:

  1. Ve a la Google Cloud Console
  2. Crea un nuevo proyecto
  3. Habilita la API de Gmail
  4. Configura la pantalla de consentimiento OAuth
  5. Crea credenciales de ID de cliente OAuth (selecciona "Aplicación de escritorio" como tipo de aplicación)
  6. Guarda el ID de cliente y el secreto de cliente
  7. Usa OAuth 2.0 para obtener tokens de acceso y renovación con los siguientes alcances:
    • https://www.googleapis.com/auth/gmail.readonly (para leer correos)
    • https://www.googleapis.com/auth/gmail.send (para enviar correos)

Renovación de tokens

Este servidor implementa la renovación automática de tokens. Cuando tu token de acceso expira, el cliente de la API de Google usará el token de renovación, el ID de cliente y el secreto de cliente para obtener un nuevo token de acceso sin requerir intervención del usuario.

Nota de seguridad

Este servidor requiere acceso directo a tus credenciales de la API de Google. Mantén siempre tus tokens y credenciales seguros y nunca los compartas con partes no confiables.

Licencia

Consulta el archivo LICENSE para más detalles.