Google MCP Tools

Integra servicios de Google como Gmail, Calendar, Drive y Tasks con MCP.

Documentación

Google MCP Tools

Esta es una colección de herramientas nativas de Google (p. ej., Gmail, Calendar) para el protocolo MCP, diseñadas para integrarse sin problemas con clientes de IA como Claude o Cursor.

Instalación rápida

Haz clic abajo para una instalación con un solo clic con .mcpb:

configuraciones JSON

{
  "mcpServers": {
    "google-mcp": {
      "command": "bunx",
      "args": ["--no-cache", "google-mcp@latest"],
      "env": {
        // Either can be used, but not both
        // Use OAuth
        "GOOGLE_OAUTH_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "GOOGLE_OAUTH_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "GOOGLE_OAUTH_TOKEN_PATH": "<PATH_TO_STORE_TOKENS> CAN_BE_ANYWHERE_ON_YOUR_SYSTEM",
        // Use Service Account
        "GOOGLE_CLIENT_EMAIL": "<YOUR_SERVICE_ACCOUNT_EMAIL>",
        "GOOGLE_PRIVATE_KEY": "<YOUR_SERVICE_ACCOUNT_PRIVATE_KEY>",
        "GMAIL_USER_TO_IMPERSONATE": "<USER_TO_IMPERSONATE>"
      }
    }
  }
}

Novedades en v1.1.0

🆕 Funciones principales

Soporte completo de archivos adjuntos en correos:
- ✉️ Enviar correos con archivos adjuntos desde archivos locales o Google Drive
- 📥 Descargar todos los archivos adjuntos de correos al almacenamiento local
- 🔄 Fuentes de archivos adjuntos duales: rutas de archivos locales o IDs de archivos de Google Drive
- 📁 Manejo inteligente de archivos: detección automática de tipo MIME y saneamiento de nombres de archivo

🔧 Capacidades de correo mejoradas

Archivos adjuntos de múltiples fuentes: adjuntar archivos desde almacenamiento local o Google Drive en el mismo correo
Nombres de archivo personalizados: sobrescribir los nombres de archivo originales de los adjuntos
Validación de tamaño de archivo: aplicación automática del límite de 25MB de Gmail
Descargas multiplataforma: detección automática de la carpeta de Descargas en Windows, macOS y Linux
Resolución de conflictos: renombrado automático de archivos para evitar sobrescrituras

📁 Herramientas nuevas y mejoradas

google_gmail_send_email: Ahora admite archivos adjuntos desde archivos locales y Google Drive
google_gmail_draft_email: Crear borradores con archivos adjuntos
google_gmail_download_attachments: Descargar todos los archivos adjuntos de correos con ruta personalizable

Funciones

Gestión de OAuth:
- Actualizar automáticamente los tokens de acceso caducados
- Actualizar los tokens en el archivo de tokens sin reautenticación
- Reautenticación completa con limpieza automatizada de tokens
- Mantener la continuidad de la sesión en operaciones de larga duración
Gmail:
- Enviar correos con múltiples destinatarios (para, cc, cco) y archivos adjuntos desde archivos locales o Google Drive.
- Descargar todos los archivos adjuntos de correos al almacenamiento local con soporte multiplataforma.
- Listar correos con consultas personalizadas, etiquetas y límites de resultados.
- Leer correos específicos por ID con información de archivos adjuntos.
- Gestionar etiquetas (agregar, eliminar, listar).
- Redactar y eliminar correos.
Calendar:
- Listar calendarios y establecer un calendario predeterminado.
- Crear eventos con detalles (resumen, hora de inicio/fin, asistentes, etc.).
- Listar próximos eventos con filtros personalizables.
- Actualizar o eliminar eventos existentes.
- Encontrar espacios de tiempo libres para programar.
Drive:
- Filtrar con consultas de búsqueda
- Ordenar por fecha de modificación u otros criterios
- Personalizar la cantidad de elementos mostrados
- Ver metadatos detallados de archivos
- Leer contenido de archivos (texto, documentos, hojas de cálculo)
- Crear archivos nuevos con contenido especificado
- Actualizar archivos existentes
- Eliminar archivos (papelera o permanentemente)
- Compartir archivos con permisos específicos
Tasks:
- Ver todas las listas de tareas
- Crear listas de tareas nuevas
- Eliminar listas de tareas existentes
- Establecer la lista de tareas predeterminada
- Listar tareas con filtros
- Ver detalles de tareas
- Crear tareas con título, notas y fechas de vencimiento
- Actualizar propiedades de tareas
- Marcar tareas como completadas
- Eliminar tareas
Planes TODO:
- Google Contacts: Buscar y gestionar contactos.
- Y muchos más...

Puedes encadenar comandos para flujos de trabajo, por ejemplo:

"Enumera mis correos no leídos, redacta una respuesta al más reciente y programa una reunión de seguimiento para mañana a las 2 PM."

Implementación alojada

Hay una implementación alojada disponible en Fronteir AI.

Gestión de tokens OAuth

El servidor incluye gestión integrada de tokens OAuth para manejar tokens de acceso caducados de forma elegante:

Actualización automática de tokens: Cuando los tokens de acceso caducan, puedes actualizarlos sin pasar por el flujo OAuth completo nuevamente
Reautenticación completa: Manejar automáticamente los casos en que los tokens de actualización son inválidos o han caducado
Almacenamiento persistente: Los tokens actualizados se guardan automáticamente en la ruta de archivo de tokens configurada
Continuidad de sesión: Todos los servicios de Google se reinicializan con tokens nuevos después de la actualización

Actualización de tokens

Si encuentras errores de autenticación o quieres actualizar tus tokens de forma proactiva, simplemente pregunta:

Refresh my Google OAuth tokens

Esto hará lo siguiente:

Usar tu token de actualización almacenado para obtener nuevos tokens de acceso
Actualizar el archivo de tokens con las nuevas credenciales
Reinicializar todos los servicios de Google con autenticación nueva
Mostrarte el nuevo tiempo de expiración del token

Reautenticación completa

Si recibes errores de invalid_grant o tu token de actualización ha caducado, puedes empezar de nuevo:

Re-authenticate my Google account

Este proceso automatizado hará lo siguiente:

Eliminar los tokens existentes de tu archivo de tokens
Iniciar el servidor OAuth para manejar la devolución de llamada
Abrir el navegador para una autenticación nueva
Guardar los tokens nuevos automáticamente
Reinicializar los servicios con credenciales nuevas

Solo necesitarás hacer clic en "Permitir" en el navegador: ¡todo lo demás está automatizado!

Nota: Si no tienes un token de actualización válido, deberás pasar por el flujo de autenticación OAuth inicial nuevamente.

Instalación manual

Requisitos previos:

Instalar Bun:

brew install oven-sh/bun/bun  # macOS/Linux with Homebrew

Configurar OAuth:
- Crea un proyecto de Google Cloud en la consola de Google Cloud.
- Configura las credenciales OAuth 2.0 (ID de cliente, secreto de cliente).
- Elige el tipo Aplicación de escritorio.
- Si usas el modo de prueba, agrega tu correo a la lista de usuarios de prueba.
- Asegúrate de habilitar el acceso a la API para los servicios deseados (Gmail, Calendar, Drive, etc.).
Configura tu cliente: Edita tu claude_desktop_config.json (o el archivo de configuración equivalente para tu cliente):

{
  "mcpServers": {
    "google-mcp": {
      "command": "bunx",
      "args": ["--no-cache", "google-mcp@latest"],
      "env": {
        // Either can be used, but not both
        // Use OAuth
        "GOOGLE_OAUTH_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "GOOGLE_OAUTH_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "GOOGLE_OAUTH_TOKEN_PATH": "<PATH_TO_STORE_TOKENS>",
        // Use Service Account
        "GOOGLE_CLIENT_EMAIL": "<YOUR_SERVICE_ACCOUNT_EMAIL>",
        "GOOGLE_PRIVATE_KEY": "<YOUR_SERVICE_ACCOUNT_PRIVATE_KEY>",
        "GMAIL_USER_TO_IMPERSONATE": "<USER_TO_IMPERSONATE>"
      }
    }
  }
}

Autenticarse:
- La primera vez que ejecutes el servidor, se abrirá un navegador para la autenticación OAuth. Sigue las indicaciones para otorgar acceso y los tokens se guardarán en GOOGLE_OAUTH_TOKEN_PATH.

Uso

Ahora, pídele a Claude que use la herramienta google-mcp.

Send an email to jane.doe@example.com with the subject "Meeting Notes" and body "Here are the notes from today."

List my upcoming calendar events for the next 3 days.

Create a calendar event titled "Team Sync" tomorrow at 10 AM for 1 hour.

Refresh my Google OAuth tokens

Re-authenticate my Google account

Soporte de transporte

Este servidor MCP admite transportes stdio y HTTP mediante variables de entorno:

Transporte stdio (predeterminado)

# Default mode - uses stdio transport
bun run dev
# Or explicitly
MCP_TRANSPORT=stdio bun run index.ts

Transporte HTTP (HTTP transmisible)

# HTTP mode with Streamable HTTP support
MCP_TRANSPORT=http bun run index.ts
# Or with custom port
MCP_TRANSPORT=http PORT=3000 bun run index.ts

Cuando se ejecuta en modo HTTP, el servidor proporciona estos endpoints:

GET /health - Endpoint de verificación de estado con recuento de sesiones
GET /mcp - Información de sesión y estado del servidor
POST /mcp - Endpoint principal MCP JSON-RPC para enviar solicitudes
DELETE /mcp - Endpoint para finalizar sesión

Gestión de sesiones

El transporte HTTP transmisible utiliza el SDK oficial de MCP con gestión automática de sesiones:

Sesiones automáticas: El servidor genera automáticamente IDs de sesión seguros
Transmisión SSE: Admite eventos enviados por el servidor para comunicación en tiempo real
Respuestas JSON: Recurre a respuestas JSON cuando SSE no está disponible
Protección DNS: Funciones de seguridad integradas para implementación en producción

Configuración para transporte HTTP

Para el transporte HTTP, configura tu cliente con la URL del servidor:

{
  "mcpServers": {
    "google-mcp-http": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Desarrollo local

git clone https://github.com/vakharwalad23/google-mcp.git
cd google-mcp
bun install

# Run in stdio mode (default)
bun run dev:stdio

# Run in HTTP mode
bun run dev:http

¡Gracias por usar Google MCP Tools! Si tienes preguntas o sugerencias, no dudes en abrir un issue o contribuir al proyecto.

¡Experimenta con las herramientas y disfruta!!