Servidor de Gmail sin cabeza MCP

Un servidor MCP (Protocolo de contexto de modelo) que permite obtener y enviar correos de Gmail sin necesidad de configurar credenciales o tokens locales.

¿Por qué elegir un servidor Gmail sin cabeza MCP?

Ventajas críticas

Operación remota y sin cabeza : a diferencia de otras soluciones MCP de Gmail que requieren ejecutarse fuera de Docker y acceder a archivos locales, este servidor puede ejecutarse completamente sin cabeza 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 credenciales como contexto a este servidor MCP, creando una separación completa entre el almacenamiento de credenciales y la implementación del servidor.

Agradable pero no crítico.

Funcionalidad enfocada : en muchos casos de uso, especialmente para 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.
Docker-Ready : diseñado teniendo en cuenta la contenedorización para una configuración con un solo clic, independiente del entorno y bien aislada.
Dependencias confiables : construida sobre la biblioteca google-api-python-client bien mantenida.

Características

Obtenga los correos electrónicos más recientes de Gmail con los primeros 1k caracteres del cuerpo
Obtenga el contenido completo del cuerpo del correo electrónico en fragmentos de 1k usando el parámetro de desplazamiento
Enviar correos electrónicos a través de Gmail
Actualizar los tokens de acceso por separado
Manejo automático de tokens de actualización

Prerrequisitos

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

Instalación

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

# Install dependencies
pip install -e .

Estibador

Construyendo la imagen de Docker

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

Uso con Claude Desktop

Uso de Docker

Puede configurar Claude Desktop para usar la imagen de Docker agregando lo siguiente a su configuración de Claude:

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

Nota: Con esta configuración, deberá proporcionar sus credenciales de la API de Google en las llamadas a herramientas, como se muestra en la sección "Uso de las herramientas" . Las credenciales de Gmail no se transfieren 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 de Docker en varias plataformas, puede usar el comando docker buildx . Siga estos pasos:

Cree una nueva instancia de constructor (si aún no lo ha hecho):
docker buildx create --use
Construya y envíe la imagen para múltiples plataformas :
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-headless-gmail:latest --push .
Verifique que la imagen esté disponible para las plataformas especificadas :
docker buildx imagetools inspect buryhuang/mcp-headless-gmail:latest

Uso

El servidor proporciona la funcionalidad de Gmail mediante herramientas MCP. La autenticación se simplifica gracias a una herramienta dedicada a la actualización de tokens.

Iniciando el servidor

mcp-server-headless-gmail

Usando las herramientas

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

Actualización de tokens (primer paso o cuando expiran)

Si tiene tokens de acceso y actualizació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 su token de acceso ha expirado, puede actualizarlo solo con el token de actualizació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 puede usar para llamadas posteriores.

Recibir correos electrónicos recientes

Recupera correos electrónicos recientes con los primeros 1k caracteres de cada cuerpo del correo electrónico:

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

La respuesta incluye:

Metadatos de correo electrónico (id, threadId, de, para, asunto, fecha, etc.)
Los primeros 1000 caracteres del cuerpo del correo electrónico
body_size_bytes : Tamaño total del cuerpo del correo electrónico en bytes
contains_full_body : valor booleano que indica si se incluye todo el cuerpo (verdadero) o se trunca (falso)

Obtener el contenido completo del cuerpo del correo electrónico

Para correos electrónicos 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 electrónico por ID del 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 electrónico a partir del desplazamiento especificado
body_size_bytes : Tamaño total del cuerpo del correo electrónico
chunk_size : Tamaño del fragmento devuelto
contains_full_body : valor booleano que indica si el fragmento contiene el resto del cuerpo

Para recuperar el cuerpo completo del correo electrónico de un mensaje largo, realice llamadas secuenciales aumentando el desplazamiento en 1000 cada vez hasta que contains_full_body sea verdadero.

Enviar un correo electrónico

{
  "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 trabajo de actualización de tokens

Comience llamando a la herramienta gmail_refresh_token con:
- Sus credenciales completas (token de acceso, token de actualización, ID de cliente y secreto de cliente), o
- Solo su token de actualización, ID de cliente y secreto de cliente si el token de acceso ha expirado
Utilice el nuevo token de acceso devuelto para llamadas API posteriores.
Si recibe una respuesta que indica la expiración del token, llame a la herramienta gmail_refresh_token nuevamente 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 y, al mismo tiempo, permite la actualización del token cuando es necesario.

Obtención de credenciales de la API de Google

Para obtener las credenciales de API de Google necesarias, siga estos pasos:

Vaya a la consola de Google Cloud
Crear un nuevo proyecto
Habilitar la API de Gmail
Configurar la pantalla de consentimiento de OAuth
Cree credenciales de ID de cliente OAuth (seleccione "Aplicación de escritorio" como tipo de aplicación)
Guardar el ID del cliente y el secreto del cliente
Utilice OAuth 2.0 para obtener tokens de acceso y actualización con los siguientes alcances:
- https://www.googleapis.com/auth/gmail.readonly (para leer correos electrónicos)
- https://www.googleapis.com/auth/gmail.send (para enviar correos electrónicos)

Actualización de tokens

Este servidor implementa la actualización automática de tokens. Cuando su token de acceso caduque, el cliente de la API de Google usará el token de actualización, el ID de cliente y el secreto de cliente para obtener un nuevo token de acceso sin necesidad de 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 terceros que no sean de confianza.

Licencia

Consulte el archivo LICENCIA para obtener más detalles.

MCP Headless Gmail Server

Integrations