Gmail AutoAuth MCP Server

Permite que los asistentes de IA gestionen Gmail mediante interacciones en lenguaje natural.

GitHubPrueba este MCPPatrocinado

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 para caracteres internacionales en asuntos y contenido de correos
  • Leer mensajes de correo por ID con manejo avanzado de estructura MIME
  • Ver información de archivos adjuntos (nombres, tipos, tamaños)
  • 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 (del sistema y definidas 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 para credenciales de aplicaciones de escritorio y 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 a través de Smithery:

npx -y @smithery/cli install @raghavared/gmail-mcp --client claude

Instalación Manual

  1. Crear un proyecto en Google Cloud y obtener credenciales:

    a. Crear un proyecto en Google Cloud:

    • Ir a Consola de Google Cloud
    • Crear un nuevo proyecto o seleccionar uno existente
    • Habilitar la API de Gmail para tu 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 aplicaciones web, agregar http://localhost:3000/v2/auth/google/callback a las URI de redireccionamiento autorizadas
    • Descargar el archivo JSON con las claves OAuth de tu cliente
    • Renombrar el archivo de claves a token.json

  2. Ejecutar la Autenticación:

    Puedes autenticarte de dos maneras:

    a. Autenticación Global (Recomendada):

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

# Run authentication from anywhere
npx @raghavared/gmail-mcp auth

    b. Autenticación Local:

    # Place token.json in your current directory
# The file will be automatically copied to global config
npx @raghavared/gmail-mcp auth

    El proceso de autenticación:

    • Buscará token.json en el directorio actual o en ~/.gmail-mcp/
    • Si se encuentra en el directorio actual, lo copiará a ~/.gmail-mcp/
    • Abrirá tu 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 de aplicación web
    • Para credenciales de aplicación web, asegúrate de agregar http://localhost:3000/v2/auth/google/callback a tus URI de redireccionamiento autorizadas

  3. Configurar en Claude Desktop:

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

Soporte para Docker

Si prefieres usar Docker:

  1. Autenticación:
docker run -i --rm \
  --mount type=bind,source=/path/to/token.json,target=/token.json \
  -v gmail-mcp:/gmail-server \
  -e GMAIL_OAUTH_PATH=/token.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",
        "gmail-mcp"
      ]
    }
  }
}

Autenticación en Servidor en la Nube

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

npx @raghavared/gmail-mcp auth {domain}/v2/auth/google/callback

Instrucciones de Configuración para Entornos en la Nube

  1. Configurar Proxy Inverso:

    • Configura tu contenedor de n8n para exponer un puerto para la autenticación
    • Configura un proxy inverso para reenviar el tráfico desde tu dominio (por ejemplo, domain.com) a este puerto

  2. Configuración de DNS:

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

  3. Configuración de la Plataforma Google Cloud:

    • En tu Consola de Google Cloud, agrega la URL de devolución de llamada de tu dominio personalizado (por ejemplo, https://domain.com/v2/auth/google/callback) a la lista de URI de redireccionamiento autorizadas

  4. Ejecutar la Autenticación:

    npx @raghavared/gmail-mcp auth https://domain.com/v2/auth/google/callback

  5. Configurar en tu aplicación:

    {
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@raghavared/gmail-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 se pueden usar a través de Claude Desktop:

1. Enviar Correo (send_email)

Envía un nuevo correo electrónico de inmediato.

{
  "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"]
}

2. Borrador de Correo (draft_email)

Crea un borrador de correo sin enviarlo.

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

3. Leer Correo (read_email)

Recupera el contenido de un correo específico por su ID.

{
  "messageId": "182ab45cd67ef"
}

4. Buscar Correos (search_emails)

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

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

5. Modificar Correo (modify_email)

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

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

6. Eliminar Correo (delete_email)

Elimina permanentemente un correo.

{
  "messageId": "182ab45cd67ef"
}

7. Listar Etiquetas de Correo (list_email_labels)

Recupera todas las etiquetas de Gmail disponibles.

{}

8. Crear Etiqueta (create_label)

Crea una nueva etiqueta de Gmail.

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

9. Actualizar Etiqueta (update_label)

Actualiza una etiqueta de Gmail existente.

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

10. Eliminar Etiqueta (delete_label)

Elimina una etiqueta de Gmail.

{
  "id": "Label_1234567890"
}

11. 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"
}

12. Modificación por Lotes de Correos (batch_modify_emails)

Modifica etiquetas de múltiples correos en lotes eficientes.

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

13. Eliminación por Lotes de Correos (batch_delete_emails)

Elimina permanentemente múltiples correos en lotes eficientes.

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

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

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

Características Avanzadas

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, tipo, tamaño)
  • 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, incluyendo:

  • 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 los correos 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 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/fallo 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 tu entorno local (~/.gmail-mcp/)
  • El servidor utiliza acceso sin conexión para mantener la autenticación persistente
  • Nunca compartas ni confirmes tus credenciales en el control de versiones
  • Revisa y revoca regularmente el acceso no utilizado en la configuración de tu cuenta de Google
  • Las credenciales se almacenan globalmente pero solo son accesibles por el usuario actual

Solución de Problemas

  1. Claves OAuth No Encontradas

    • Asegúrate de que token.json esté en tu directorio actual o en ~/.gmail-mcp/
    • Verifica los permisos de archivo

  2. Formato de Credenciales Inválido

    • Asegúrate de que tu archivo de claves OAuth contenga credenciales de web o installed
    • Para aplicaciones web, verifica que la URI de redireccionamiento esté configurada correctamente

  3. Puerto Ya en Uso

    • Si el puerto 3000 ya está en uso, libéralo antes de ejecutar la autenticación
    • Puedes 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
    • Revisa los mensajes de error detallados para fallos específicos
    • Considera reducir el tamaño del lote si encuentras limitaciones de velocidad

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request).

Licencia

MIT

Soporte

Si encuentras algún problema o tienes preguntas, por favor reporta un problema en el repositorio de GitHub.