Gmail AutoAuth MCP Server

Un servidor MCP para integrar Gmail con soporte de autenticación automática.

GitHub
1.2k

Documentación

Servidor MCP Gmail AutoAuth

Un servidor de Protocolo de Contexto de Modelo (MCP) para la integración de Gmail en Claude Desktop con soporte de autenticación automática. Este servidor permite a los asistentes de IA gestionar Gmail mediante interacciones en lenguaje natural.

smithery badge

Características

  • Enviar correos electrónicos con asunto, contenido, archivos adjuntos y destinatarios
  • Soporte completo de archivos adjuntos: enviar y recibir archivos adjuntos
  • Descargar archivos adjuntos de correos al sistema de archivos local
  • Soporte para correos HTML y mensajes multiparte con versiones tanto HTML como de texto plano
  • Soporte completo para caracteres internacionales en líneas de asunto y contenido de correos
  • Leer mensajes de correo por ID con manejo avanzado de estructura MIME
  • Visualización mejorada de archivos adjuntos que muestra nombres de archivo, tipos, tamaños e IDs de descarga
  • Buscar correos con varios criterios (asunto, remitente, rango de fechas)
  • Gestión integral de etiquetas con capacidad para crear, actualizar, eliminar y listar etiquetas
  • Listar todas las etiquetas de Gmail disponibles (definidas por el sistema y por el usuario)
  • Listar correos en la bandeja de entrada, enviados o etiquetas personalizadas
  • Marcar correos como leídos/no leídos
  • Mover correos a diferentes etiquetas/carpetas
  • Eliminar correos
  • Operaciones por lotes para procesar eficientemente múltiples correos a la vez
  • Integración completa con la API de Gmail
  • Flujo de autenticación OAuth2 simple con apertura automática del navegador
  • Soporte tanto para credenciales de aplicación de escritorio como web
  • Almacenamiento global de credenciales para mayor comodidad

Instalación y Autenticación

Instalación mediante Smithery

Para instalar Gmail AutoAuth para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude

Instalación Manual

  1. Crear un Proyecto de Google Cloud y obtener credenciales:

    a. Crear un Proyecto de Google Cloud:

    • Ir a Consola de Google Cloud
    • Crear un nuevo proyecto o seleccionar uno existente
    • Habilitar la API de Gmail para su proyecto

    b. Crear Credenciales OAuth 2.0:

    • Ir a "APIs y Servicios" > "Credenciales"
    • Hacer clic en "Crear credenciales" > "ID de cliente OAuth"
    • Elegir "Aplicación de escritorio" o "Aplicación web" como tipo de aplicación
    • Asignarle un nombre y hacer clic en "Crear"
    • Para aplicación web, agregar http://localhost:3000/oauth2callback a las URI de redireccionamiento autorizadas
    • Descargar el archivo JSON de las claves OAuth de su cliente
    • Renombrar el archivo de claves a gcp-oauth.keys.json

  2. Ejecutar la Autenticación:

    Puede autenticarse de dos maneras:

    a. Autenticación Global (Recomendada):

    # First time: Place gcp-oauth.keys.json in your home directory's .gmail-mcp folder
mkdir -p ~/.gmail-mcp
mv gcp-oauth.keys.json ~/.gmail-mcp/

# Run authentication from anywhere
npx @gongrzhe/server-gmail-autoauth-mcp auth

    b. Autenticación Local:

    # Place gcp-oauth.keys.json in your current directory
# The file will be automatically copied to global config
npx @gongrzhe/server-gmail-autoauth-mcp auth

    El proceso de autenticación:

    • Buscará gcp-oauth.keys.json en el directorio actual o ~/.gmail-mcp/
    • Si se encuentra en el directorio actual, lo copiará a ~/.gmail-mcp/
    • Abrirá su navegador predeterminado para la autenticación de Google
    • Guardará las credenciales como ~/.gmail-mcp/credentials.json

    Nota:

    • Después de una autenticación exitosa, las credenciales se almacenan globalmente en ~/.gmail-mcp/ y pueden usarse desde cualquier directorio
    • Se admiten tanto credenciales de aplicación de escritorio como web
    • Para credenciales de aplicación web, asegúrese de agregar http://localhost:3000/oauth2callback a sus URI de redireccionamiento autorizadas

  3. Configurar en Claude Desktop:

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

Soporte para Docker

Si prefiere usar Docker:

  1. Autenticación:
docker run -i --rm \
  --mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
  -v mcp-gmail:/gmail-server \
  -e GMAIL_OAUTH_PATH=/gcp-oauth.keys.json \
  -e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \
  -p 3000:3000 \
  mcp/gmail auth
  1. Uso:
{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "mcp-gmail:/gmail-server",
        "-e",
        "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json",
        "mcp/gmail"
      ]
    }
  }
}

Autenticación en Servidor en la Nube

Para entornos de servidor en la nube (como n8n), puede especificar una URL de devolución de llamada personalizada durante la autenticación:

npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback

Instrucciones de Configuración para Entornos en la Nube

  1. Configurar Proxy Inverso:

    • Configure su contenedor n8n para exponer un puerto para la autenticación
    • Configure un proxy inverso para reenviar el tráfico desde su dominio (por ejemplo, gmail.gongrzhe.com) a este puerto

  2. Configuración de DNS:

    • Agregue un registro A en su configuración de DNS para resolver su dominio a la dirección IP de su servidor en la nube

  3. Configuración de la Plataforma de Google Cloud:

    • En su Consola de Google Cloud, agregue la URL de devolución de llamada de su dominio personalizado (por ejemplo, https://gmail.gongrzhe.com/oauth2callback) a la lista de URI de redireccionamiento autorizadas

  4. Ejecutar la Autenticación:

    npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback

  5. Configurar en su aplicación:

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

Este enfoque permite que los flujos de autenticación funcionen correctamente en entornos donde localhost no es accesible, como aplicaciones contenedorizadas o servidores en la nube.

Herramientas Disponibles

El servidor proporciona las siguientes herramientas que pueden usarse a través de Claude Desktop:

1. Enviar Correo (send_email)

Envía un nuevo correo electrónico de inmediato. Admite correos de texto plano, HTML o multiparte con archivos adjuntos opcionales.

Correo Básico:

{
  "to": ["recipient@example.com"],
  "subject": "Meeting Tomorrow",
  "body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"],
  "mimeType": "text/plain"
}

Correo con Archivos Adjuntos:

{
  "to": ["recipient@example.com"],
  "subject": "Project Files",
  "body": "Hi,\n\nPlease find the project files attached.\n\nBest regards",
  "attachments": [
    "/path/to/document.pdf",
    "/path/to/spreadsheet.xlsx",
    "/path/to/presentation.pptx"
  ]
}

Ejemplo de Correo HTML:

{
  "to": ["recipient@example.com"],
  "subject": "Meeting Tomorrow",
  "mimeType": "text/html",
  "body": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}

Ejemplo de Correo Multiparte (HTML + Texto Plano):

{
  "to": ["recipient@example.com"],
  "subject": "Meeting Tomorrow",
  "mimeType": "multipart/alternative",
  "body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
  "htmlBody": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}

2. Borrador de Correo (draft_email)

Crea un borrador de correo sin enviarlo. También admite archivos adjuntos.

{
  "to": ["recipient@example.com"],
  "subject": "Draft Report",
  "body": "Here's the draft report for your review.",
  "cc": ["manager@example.com"],
  "attachments": ["/path/to/draft_report.docx"]
}

3. Leer Correo (read_email)

Recupera el contenido de un correo específico por su ID. Ahora muestra información mejorada de archivos adjuntos.

{
  "messageId": "182ab45cd67ef"
}

La respuesta mejorada incluye detalles de archivos adjuntos:

Subject: Project Files
From: sender@example.com
To: recipient@example.com
Date: Thu, 19 Jun 2025 10:30:00 -0400

Email body content here...

Attachments (2):
- document.pdf (application/pdf, 245 KB, ID: ANGjdJ9fkTs-i3GCQo5o97f_itG...)
- spreadsheet.xlsx (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, 89 KB, ID: BWHkeL8gkUt-j4HDRp6o98g_juI...)

4. Descargar Archivo Adjunto (download_attachment)

NUEVO: Descarga archivos adjuntos de correos a su sistema de archivos local.

{
  "messageId": "182ab45cd67ef",
  "attachmentId": "ANGjdJ9fkTs-i3GCQo5o97f_itG...",
  "savePath": "/path/to/downloads",
  "filename": "downloaded_document.pdf"
}

Parámetros:

  • messageId: El ID del correo que contiene el archivo adjunto
  • attachmentId: El ID del archivo adjunto (se muestra en la visualización mejorada del correo)
  • savePath: Directorio para guardar el archivo (opcional, por defecto el directorio actual)
  • filename: Nombre de archivo personalizado (opcional, usa el nombre original si no se proporciona)

5. Buscar Correos (search_emails)

Busca correos utilizando la sintaxis de búsqueda de Gmail.

{
  "query": "from:sender@example.com after:2024/01/01 has:attachment",
  "maxResults": 10
}

6. Modificar Correo (modify_email)

Agrega o elimina etiquetas de correos (mover a diferentes carpetas, archivar, etc.).

{
  "messageId": "182ab45cd67ef",
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"]
}

7. Eliminar Correo (delete_email)

Elimina permanentemente un correo.

{
  "messageId": "182ab45cd67ef"
}

8. Listar Etiquetas de Correo (list_email_labels)

Recupera todas las etiquetas de Gmail disponibles.

{}

9. Crear Etiqueta (create_label)

Crea una nueva etiqueta de Gmail.

{
  "name": "Important Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

10. Actualizar Etiqueta (update_label)

Actualiza una etiqueta de Gmail existente.

{
  "id": "Label_1234567890",
  "name": "Urgent Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

11. Eliminar Etiqueta (delete_label)

Elimina una etiqueta de Gmail.

{
  "id": "Label_1234567890"
}

12. Obtener o Crear Etiqueta (get_or_create_label)

Obtiene una etiqueta existente por nombre o la crea si no existe.

{
  "name": "Project XYZ",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

13. Modificar Correos por Lote (batch_modify_emails)

Modifica etiquetas de múltiples correos en lotes eficientes.

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"],
  "batchSize": 50
}

14. Eliminar Correos por Lote (batch_delete_emails)

Elimina permanentemente múltiples correos en lotes eficientes.

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "batchSize": 50
}

14. Crear Filtro (create_filter)

Crea un nuevo filtro de Gmail con criterios y acciones personalizados.

{
  "criteria": {
    "from": "newsletter@company.com",
    "hasAttachment": false
  },
  "action": {
    "addLabelIds": ["Label_Newsletter"],
    "removeLabelIds": ["INBOX"]
  }
}

15. Listar Filtros (list_filters)

Recupera todos los filtros de Gmail.

{}

16. Obtener Filtro (get_filter)

Obtiene los detalles de un filtro de Gmail específico.

{
  "filterId": "ANe1Bmj1234567890"
}

17. Eliminar Filtro (delete_filter)

Elimina un filtro de Gmail.

{
  "filterId": "ANe1Bmj1234567890"
}

18. Crear Filtro desde Plantilla (create_filter_from_template)

Crea un filtro utilizando plantillas predefinidas para escenarios comunes.

{
  "template": "fromSender",
  "parameters": {
    "senderEmail": "notifications@github.com",
    "labelIds": ["Label_GitHub"],
    "archive": true
  }
}

Funciones de Gestión de Filtros

Criterios de Filtro

Puede crear filtros basados en varios criterios:

CriterioEjemploDescripción
from"sender@example.com"Correos de un remitente específico
to"recipient@example.com"Correos enviados a un destinatario específico
subject"Meeting"Correos con texto específico en el asunto
query"has:attachment"Sintaxis de consulta de búsqueda de Gmail
negatedQuery"spam"Texto que NO debe estar presente
hasAttachmenttrueCorreos con archivos adjuntos
size10485760Tamaño del correo en bytes
sizeComparison"larger"Comparación de tamaño (larger, smaller)

Acciones de Filtro

Los filtros pueden realizar las siguientes acciones:

AcciónEjemploDescripción
addLabelIds["IMPORTANT", "Label_Work"]Agregar etiquetas a los correos que coincidan
removeLabelIds["INBOX", "UNREAD"]Eliminar etiquetas de los correos que coincidan
forward"backup@example.com"Reenviar correos a otra dirección

Plantillas de Filtro

El servidor incluye plantillas preconstruidas para escenarios comunes de filtrado:

1. Plantilla de Remitente (fromSender)

Filtra correos de un remitente específico y opcionalmente los archiva.

{
  "template": "fromSender",
  "parameters": {
    "senderEmail": "newsletter@company.com",
    "labelIds": ["Label_Newsletter"],
    "archive": true
  }
}

2. Plantilla de Filtro por Asunto (withSubject)

Filtra correos con texto específico en el asunto y opcionalmente los marca como leídos.

{
  "template": "withSubject",
  "parameters": {
    "subjectText": "[URGENT]",
    "labelIds": ["Label_Urgent"],
    "markAsRead": false
  }
}

3. Plantilla de Filtro por Archivos Adjuntos (withAttachments)

Filtra todos los correos con archivos adjuntos.

{
  "template": "withAttachments",
  "parameters": {
    "labelIds": ["Label_Attachments"]
  }
}

4. Plantilla de Correos Grandes (largeEmails)

Filtra correos más grandes que un tamaño especificado.

{
  "template": "largeEmails",
  "parameters": {
    "sizeInBytes": 10485760,
    "labelIds": ["Label_Large"]
  }
}

5. Plantilla de Filtro por Contenido (containingText)

Filtra correos que contienen texto específico y opcionalmente los marca como importantes.

{
  "template": "containingText",
  "parameters": {
    "searchText": "invoice",
    "labelIds": ["Label_Finance"],
    "markImportant": true
  }
}

6. Plantilla de Lista de Correo (mailingList)

Filtra correos de listas de correo y opcionalmente los archiva.

{
  "template": "mailingList",
  "parameters": {
    "listIdentifier": "dev-team",
    "labelIds": ["Label_DevTeam"],
    "archive": true
  }
}

Ejemplos Comunes de Filtros

Aquí hay algunos ejemplos prácticos de filtros:

Organizar automáticamente boletines:

{
  "criteria": {
    "from": "newsletter@company.com"
  },
  "action": {
    "addLabelIds": ["Label_Newsletter"],
    "removeLabelIds": ["INBOX"]
  }
}

Manejar correos promocionales:

{
  "criteria": {
    "query": "unsubscribe OR promotional"
  },
  "action": {
    "addLabelIds": ["Label_Promotions"],
    "removeLabelIds": ["INBOX", "UNREAD"]
  }
}

Correos prioritarios del jefe:

{
  "criteria": {
    "from": "boss@company.com"
  },
  "action": {
    "addLabelIds": ["IMPORTANT", "Label_Boss"]
  }
}

Archivos adjuntos grandes:

{
  "criteria": {
    "size": 10485760,
    "sizeComparison": "larger",
    "hasAttachment": true
  },
  "action": {
    "addLabelIds": ["Label_LargeFiles"]
  }
}

Sintaxis de Búsqueda Avanzada

La herramienta search_emails admite los potentes operadores de búsqueda de Gmail:

OperadorEjemploDescripción
from:from:john@example.comCorreos de un remitente específico
to:to:mary@example.comCorreos enviados a un destinatario específico
subject:subject:"meeting notes"Correos con texto específico en el asunto
has:attachmenthas:attachmentCorreos con archivos adjuntos
after:after:2024/01/01Correos recibidos después de una fecha
before:before:2024/02/01Correos recibidos antes de una fecha
is:is:unreadCorreos con un estado específico
label:label:workCorreos con una etiqueta específica

Puede combinar múltiples operadores: from:john@example.com after:2024/01/01 has:attachment

Funciones Avanzadas

Soporte de Archivos Adjuntos en Correos

El servidor proporciona funcionalidad integral de archivos adjuntos:

  • Envío de Archivos Adjuntos: Incluya rutas de archivo en el arreglo attachments al enviar o redactar correos
  • Detección de Archivos Adjuntos: Detecta automáticamente tipos MIME y tamaños de archivo
  • Capacidad de Descarga: Descargue cualquier archivo adjunto de correo a su sistema de archivos local
  • Visualización Mejorada: Vea información detallada de archivos adjuntos, incluidos nombres de archivo, tipos, tamaños e IDs de descarga
  • Múltiples Formatos: Soporte para todos los tipos de archivo comunes (documentos, imágenes, archivos comprimidos, etc.)
  • Cumplimiento RFC822: Utiliza Nodemailer para un formato adecuado de mensajes MIME

Tipos de Archivo Soportados: Todos los tipos de archivo estándar, incluidos PDF, DOCX, XLSX, PPTX, imágenes (PNG, JPG, GIF), archivos comprimidos (ZIP, RAR) y más.

Extracción de Contenido de Correos

El servidor extrae inteligentemente el contenido de los correos de estructuras MIME complejas:

  • Prioriza el contenido de texto plano cuando está disponible
  • Recurre al contenido HTML si el texto plano no está disponible
  • Maneja mensajes MIME de múltiples partes con partes anidadas
  • Procesa información de archivos adjuntos (nombre de archivo, tipo, tamaño, ID de descarga)
  • Preserva los encabezados originales del correo (De, Para, Asunto, Fecha)

Soporte de Caracteres Internacionales

El servidor admite completamente caracteres no ASCII en asuntos y contenido de correos, incluidos:

  • Alfabetos turco, chino, japonés, coreano y otros no latinos
  • Caracteres especiales y símbolos
  • La codificación adecuada garantiza la visualización correcta en los clientes de correo

Gestión Integral de Etiquetas

El servidor proporciona un conjunto completo de herramientas para gestionar etiquetas de Gmail:

  • Crear etiquetas: Crear nuevas etiquetas con configuraciones de visibilidad personalizables
  • Actualizar etiquetas: Renombrar etiquetas o cambiar sus configuraciones de visibilidad
  • Eliminar etiquetas: Eliminar etiquetas creadas por el usuario (las etiquetas del sistema están protegidas)
  • Buscar o crear: Obtener una etiqueta por nombre o crearla automáticamente si no se encuentra
  • Listar todas las etiquetas: Ver todas las etiquetas del sistema y del usuario con información detallada
  • Opciones de visibilidad de etiquetas: Controlar cómo aparecen las etiquetas en las listas de mensajes y etiquetas

Las configuraciones de visibilidad de etiquetas incluyen:

  • messageListVisibility: Controla si la etiqueta aparece en la lista de mensajes (show o hide)
  • labelListVisibility: Controla cómo aparece la etiqueta en la lista de etiquetas (labelShow, labelShowIfUnread o labelHide)

Estas funciones de gestión de etiquetas permiten una organización sofisticada de correos electrónicos directamente a través de Claude, sin necesidad de cambiar a la interfaz de Gmail.

Operaciones por lotes

El servidor incluye capacidades eficientes de procesamiento por lotes:

  • Procesar hasta 50 correos electrónicos a la vez (tamaño de lote configurable)
  • División automática de grandes conjuntos de correos para evitar límites de API
  • Informes detallados de éxito/fracaso para cada operación
  • Manejo elegante de errores con reintentos individuales
  • Perfecto para la gestión masiva de la bandeja de entrada y tareas de organización

Notas de seguridad

  • Las credenciales OAuth se almacenan de forma segura en su entorno local (~/.gmail-mcp/)
  • El servidor utiliza acceso sin conexión para mantener la autenticación persistente
  • Nunca comparta ni confirme sus credenciales en el control de versiones
  • Revise y revoque regularmente el acceso no utilizado en la configuración de su cuenta de Google
  • Las credenciales se almacenan globalmente pero solo son accesibles por el usuario actual
  • Los archivos adjuntos se procesan localmente y el servidor nunca los almacena permanentemente

Solución de problemas

  1. Claves OAuth no encontradas

    • Asegúrese de que gcp-oauth.keys.json esté en su directorio actual o en ~/.gmail-mcp/
    • Verifique los permisos de archivo

  2. Formato de credenciales no válido

    • Asegúrese de que su archivo de claves OAuth contenga credenciales web o installed
    • Para aplicaciones web, verifique que la URI de redirección esté configurada correctamente

  3. Puerto ya en uso

    • Si el puerto 3000 ya está en uso, libérelo antes de ejecutar la autenticación
    • Puede encontrar y detener el proceso que usa ese puerto

  4. Fallos en operaciones por lotes

    • Si las operaciones por lotes fallan, reintentan automáticamente los elementos individuales
    • Revise los mensajes de error detallados para fallos específicos
    • Considere reducir el tamaño del lote si encuentra limitación de velocidad

  5. Problemas con archivos adjuntos

    • Archivo no encontrado: Asegúrese de que las rutas de los archivos adjuntos sean correctas y accesibles
    • Errores de permisos: Verifique que el servidor tenga acceso de lectura a los archivos adjuntos
    • Límites de tamaño: Gmail tiene un límite de tamaño de archivo adjunto de 25 MB por correo electrónico
    • Fallos de descarga: Verifique que tenga permisos de escritura en el directorio de descarga

Contribuciones

¡Las contribuciones son bienvenidas! No dude en enviar una solicitud de extracción (Pull Request).

Ejecución de evaluaciones

El paquete de evaluaciones carga un cliente mcp que luego ejecuta el archivo index.ts, por lo que no es necesario reconstruir entre pruebas. Puede cargar variables de entorno prefijando el comando npx. La documentación completa se puede encontrar aquí.

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/index.ts

Licencia

MIT

Soporte

Si encuentra algún problema o tiene preguntas, por favor abra un problema en el repositorio de GitHub.