Google Calendar

Integra Google Calendar con seguridad mejorada usando credenciales OAuth2.

GitHub
59

Documentación

Servidor MCP de Google Calendar

Apr-15-2025 12-17-08

🔔 AVISO DE ACTUALIZACIÓN DE VERSIÓN 🔔
La versión 2.0.0 migra a la revisión de protocolo MCP 2026-07-28 e implementa PKCE en el flujo OAuth. Requiere Node.js 20 o superior. Consulta el historial de versiones a continuación para ver la lista completa de cambios.

Version License

日本語 English

Resumen del Proyecto

El Servidor MCP de Google Calendar es una implementación de servidor MCP (Protocolo de Contexto de Modelo) que permite la integración entre Google Calendar y Claude Desktop. Este proyecto permite a Claude interactuar con el Google Calendar del usuario, proporcionando la capacidad de mostrar, crear, actualizar y eliminar eventos de calendario mediante interacción en lenguaje natural.

Características Principales

  • Integración con Google Calendar: Proporciona un puente entre Claude Desktop y la API de Google Calendar
  • Implementación MCP: Sigue la especificación del Protocolo de Contexto de Modelo para la integración de herramientas de asistentes de IA
  • Autenticación OAuth2: Gestiona el flujo de autenticación de la API de Google de forma segura
  • Gestión de eventos: Admite operaciones completas de eventos de calendario (obtener, crear, actualizar, eliminar)
  • Soporte de colores: Capacidad de establecer y actualizar colores de eventos mediante el parámetro colorId
  • Transporte STDIO: Utiliza entrada/salida estándar para la comunicación con Claude Desktop

Arquitectura Técnica

Este proyecto utiliza:

  • TypeScript: Para el desarrollo de código con seguridad de tipos
  • SDK MCP: Utiliza @modelcontextprotocol/server v2 (revisión de protocolo 2026-07-28, con las revisiones de 2025 aún disponibles para clientes antiguos)
  • API de Google: Utiliza googleapis para el acceso a la API de Google Calendar
  • Hono: Framework web ligero y rápido para el servidor de autenticación
  • google-auth-library: Gestiona el flujo de código de autorización OAuth2 con PKCE (S256)
  • Zod: Implementa la validación de esquemas para datos de solicitud/respuesta
  • Configuración basada en entorno: Utiliza dotenv para la gestión de configuración
  • AES-256-GCM: Para el cifrado de tokens mediante el módulo crypto de Node.js
  • Open: Para el lanzamiento automático del navegador durante la autenticación
  • Readline: Para la entrada de autenticación manual en entornos de servidor
  • Jest: Para pruebas unitarias y cobertura
  • GitHub Actions: Para CI/CD

Componentes Principales

  1. Servidor MCP: Implementación central del servidor que gestiona la comunicación con Claude Desktop
  2. Herramientas de Google Calendar: Operaciones de calendario (recuperación, creación, actualización, eliminación)
  3. Manejador de Autenticación: Gestión del flujo OAuth2 con la API de Google
  4. Validación de Esquemas: Garantiza la integridad de los datos en todas las operaciones
  5. Gestor de Tokens: Manejo seguro de los tokens de autenticación

Herramientas Disponibles

Este servidor MCP proporciona las siguientes herramientas para interactuar con Google Calendar:

1. getEvents

Recupera eventos de calendario con varias opciones de filtrado.

Parámetros:

  • calendarId (opcional): ID del calendario (utiliza el calendario principal si se omite, cadena vacía, null o undefined)
  • timeMin (opcional): Hora de inicio para la recuperación de eventos (formato ISO 8601, p. ej., "2025-03-01T00:00:00Z"). Las cadenas vacías, null o undefined se ignoran
  • timeMax (opcional): Hora de finalización para la recuperación de eventos (formato ISO 8601). Las cadenas vacías, null o undefined se ignoran
  • maxResults (opcional): Número máximo de eventos a recuperar (predeterminado: 10)
  • orderBy (opcional): Orden de clasificación ("startTime" o "updated"). Se establece en "startTime" por defecto si es cadena vacía, null o undefined

2. createEvent

Crea un nuevo evento de calendario.

Parámetros:

  • calendarId (opcional): ID del calendario (utiliza el calendario principal si se omite)
  • event: Objeto de detalles del evento que contiene:
    • summary (obligatorio): Título del evento
    • description (opcional): Descripción del evento
    • location (opcional): Ubicación del evento
    • start: Objeto de hora de inicio con:
      • dateTime (opcional): Formato ISO 8601 (p. ej., "2025-03-15T09:00:00+09:00")
      • date (opcional): Formato AAAA-MM-DD para eventos de día completo
      • timeZone (opcional): Zona horaria (p. ej., "Asia/Tokyo")
    • end: Objeto de hora de finalización (mismo formato que el de inicio)
    • attendees (opcional): Matriz de asistentes con correo electrónico y displayName opcional
    • colorId (opcional): ID de color del evento (1-11)
    • recurrence (opcional): Matriz de reglas de recurrencia en formato RFC5545 (p. ej., ["RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR"])

3. updateEvent

Actualiza un evento de calendario existente. La función primero obtiene los datos del evento existente y los combina con los datos de actualización, conservando los campos que no están incluidos en la solicitud de actualización.

Parámetros:

  • calendarId (opcional): ID del calendario (utiliza el calendario principal si se omite)
  • eventId (obligatorio): ID del evento a actualizar
  • event: Objeto de detalles del evento que contiene los campos a actualizar (misma estructura que createEvent, todos los campos opcionales)
    • Solo se actualizarán los campos proporcionados explícitamente
    • Los campos no incluidos en la solicitud de actualización conservarán sus valores existentes
    • Esto permite actualizaciones parciales sin pérdida de datos
    • El parámetro recurrence se puede actualizar para modificar patrones de eventos recurrentes

4. deleteEvent

Elimina un evento de calendario.

Parámetros:

  • calendarId (opcional): ID del calendario (utiliza el calendario principal si se omite)
  • eventId (obligatorio): ID del evento a eliminar

5. authenticate

Reautentica con Google Calendar. Esto es útil cuando deseas cambiar entre diferentes cuentas de Google sin tener que reiniciar Claude.

Parámetros:

  • Ninguno

Directrices de Desarrollo

Al agregar nuevas funciones, modificar código o corregir errores, aumenta semánticamente la versión para cada cambio usando el comando npm version. Además, asegúrate de que tu código sea claro y siga todas las reglas de codificación necesarias, como OOP. El script de versión ejecutará automáticamente npm install cuando se actualice la versión, pero aun así debes compilar, ejecutar lint y probar tu código antes de enviarlo.

Estructura del Código

  • src/: Directorio de código fuente
    • auth/: Manejo de autenticación (flujo OAuth con PKCE, almacenamiento de tokens)
    • calendar/: Integración con la API de Google Calendar
    • config/: Configuración y validación
    • mcp/: Implementación del servidor MCP
      • tools/: Manejadores de herramientas de Google Calendar
    • utils/: Funciones y utilidades auxiliares

Buenas Prácticas

  • Tipado adecuado según las mejores prácticas de TypeScript
  • Mantener un manejo integral de errores
  • Garantizar un flujo de autenticación adecuado
  • Mantener las dependencias actualizadas
  • Escribir documentación clara para todas las funciones
  • Implementar mejores prácticas de seguridad
  • Seguir los estándares de autenticación OAuth 2.1
  • Usar validación de esquemas para todos los datos de entrada/salida

Pruebas

  • Implementar pruebas unitarias para la funcionalidad principal
  • Probar exhaustivamente el flujo de autenticación
  • Verificar la manipulación del calendario contra la API de Google
  • Ejecutar pruebas con informes de cobertura
  • Asegurarse de que se incluyan pruebas de seguridad

Despliegue

Este paquete se publica en npm como @takumi0706/google-calendar-mcp:

npx @takumi0706/google-calendar-mcp@2.0.0

Requisitos Previos

  1. Node.js 20 o superior
  2. Crear un Proyecto de Google Cloud y habilitar la API de Google Calendar
  3. Configurar las credenciales OAuth2 en la Consola de Google Cloud
  4. Configurar las variables de entorno:
# Create a .env file with your Google OAuth credentials
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:4153/oauth2callback
# Optional: Token encryption key (auto-generated if not provided)
TOKEN_ENCRYPTION_KEY=32-byte-hex-key
# Optional: Auth server port and host (default port: 4153, host: localhost)
AUTH_PORT=4153
AUTH_HOST=localhost
# Optional: MCP server port and host (default port: 3000, host: localhost)
PORT=3000
HOST=localhost
# Optional: Enable manual authentication (useful when localhost is not accessible)
USE_MANUAL_AUTH=true

Configuración de Claude Desktop

Agrega el servidor a tu claude_desktop_config.json. Si estás ejecutando en un entorno donde localhost no es accesible, agrega la variable de entorno USE_MANUAL_AUTH establecida en "true".

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": [
        "-y",
        "@takumi0706/google-calendar-mcp"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:4153/oauth2callback"
      }
    }
  }
}

Consideraciones de Seguridad

  • Los tokens OAuth se almacenan solo en memoria (no se almacenan en un almacenamiento basado en archivos). Se pierden al reiniciar, lo que significa que se requiere reautenticación después de cada reinicio.
  • Las credenciales sensibles deben proporcionarse como variables de entorno
  • Cifrado de tokens mediante AES-256-GCM mientras los tokens están en memoria. Ten en cuenta que la clave reside en el mismo proceso que el texto cifrado, por lo que esto protege contra la inspección casual de la memoria del proceso, no contra un atacante que ya pueda leer la memoria de este proceso.
  • PKCE (S256) en el flujo de código de autorización, con un code_verifier generado por solicitud y nunca enviado al punto final de autorización
  • Validación del parámetro de estado para protección CSRF: estado CSPRNG de 256 bits, comparado en tiempo constante, de un solo uso y con caducidad después de 10 minutos
  • URI de redirección fija tomada de la configuración en lugar de la cabecera Host de la solicitud
  • Validación de entrada con esquema Zod
  • Escapado de HTML en cada valor interpolado en las páginas de resultados de OAuth

Para más detalles, consulta SECURITY.md.

Mantenimiento

  • Actualizaciones periódicas para mantener la compatibilidad con la API de Google Calendar
  • Las actualizaciones de versión se documentan en README.md

Solución de Problemas

Si encuentras algún problema:

  1. Asegúrate de que tus credenciales OAuth de Google estén configuradas correctamente
  2. Asegúrate de tener permisos suficientes para el acceso a la API de Google Calendar
  3. Verifica que tu configuración de Claude Desktop sea correcta

Errores Comunes

  • Errores de análisis JSON: Si ves errores como Unexpected non-whitespace character after JSON at position 4 (line 1 column 5), generalmente se deben a mensajes JSON-RPC mal formados. Este problema se ha corregido en la versión 0.6.7 y posteriores. Si aún experimentas estos errores, actualiza a la última versión.
  • Errores de autenticación: Verifica tus credenciales OAuth de Google
  • Parámetro de estado no válido: Si ves Authentication failed: Invalid state parameter al reautenticar, actualiza a la versión 1.0.3 o posterior, que corrige la gestión del ciclo de vida del servidor OAuth. En versiones anteriores, es posible que debas cerrar el puerto 4153 y reiniciar la aplicación.
  • Errores de conexión: Asegúrate de que solo se esté ejecutando una instancia del servidor
  • Problemas de desconexión: Asegúrate de que tu servidor maneje correctamente los mensajes MCP sin sockets TCP personalizados
  • No se puede acceder a localhost: Si estás ejecutando la aplicación en un entorno donde localhost no es accesible (como un servidor remoto o contenedor), habilita la autenticación manual configurando USE_MANUAL_AUTH=true. Esto te permitirá ingresar manualmente el código de autorización que muestra Google después de autorizar la aplicación.
  • Errores de validación de parámetros MCP: Si ves el error -32602 con parámetros de cadena vacía, actualiza a la versión 1.0.7 o posterior, que maneja correctamente cadenas vacías, null y undefined.

Historial de Versiones

Cambios de la Versión 2.0.0

Seguridad

  • Implementado PKCE (S256) en el flujo de código de autorización OAuth. Las versiones anteriores documentaban PKCE pero nunca enviaban un code_challenge.
  • El parámetro state ahora es un valor CSPRNG de 256 bits, comparado en tiempo constante, de un solo uso y con caducidad después de 10 minutos. Anteriormente se generaba con Math.random().
  • Corregido un XSS reflejado en la página de error de OAuth: los detalles del error ahora se registran en lugar de interpolarse en HTML, y cada valor interpolado se escapa.
  • redirect_uri está fijado al valor configurado en lugar de derivarse de la cabecera Host de la solicitud.
  • El servidor de autorización local ahora se aborta cuando su puerto ya está en uso, en lugar de asumir que otra instancia está sirviendo el flujo.
  • TOKEN_ENCRYPTION_KEY ahora debe tener exactamente 64 caracteres hexadecimales; las claves no válidas y de todo ceros se rechazan al inicio.
  • Resueltas todas las vulnerabilidades conocidas en las dependencias de producción.

Protocolo

  • Migrado a @modelcontextprotocol/server v2 y revisión de protocolo 2026-07-28. Las revisiones de 2025 aún se sirven, por lo que los clientes existentes siguen funcionando.
  • tools/list ahora anuncia el esquema real, por lo que los objetos anidados como el argumento event de createEvent exponen sus propiedades. Anteriormente eran opacos.
  • prompts/get ahora está implementado. El servidor anunciaba diez prompts que no se podían obtener.
  • resources/read ahora devuelve la forma que requiere la especificación.
  • initialize ya no filtra internos de Zod a través de capabilities.

Cambios Importantes

  • Requiere Node.js 20 o superior.

Otros

  • Se migró el conjunto de herramientas a pnpm, se actualizaron googleapis, hono y zod, y se eliminó @hono/oauth-providers.
  • Se eliminaron any y las aserciones de tipo del código publicado, aplicadas mediante lint.

Cambios en la versión 1.0.7

  • Validación de parámetros mejorada para las herramientas MCP para manejar correctamente cadenas vacías, valores nulos e indefinidos.
  • Se corrigió el error MCP -32602 cuando se pasaban parámetros de cadena vacía a la herramienta getEvents.
  • Se mejoró la función preprocessArgs para omitir valores vacíos, permitiendo que los valores predeterminados del esquema Zod se apliquen correctamente.
  • Se añadió una cobertura de pruebas integral para el manejo de parámetros vacíos.

Cambios en la versión 1.0.6

  • Se corrigió que el alcance no es necesario en este servidor MCP de Google Calendar.

Cambios en la versión 1.0.5

  • Se añadió soporte para eventos recurrentes mediante el parámetro recurrence en las herramientas createEvent y updateEvent.
  • Permite la creación y modificación de eventos recurrentes directamente sin configuración manual.

Cambios en la versión 1.0.4

  • Versión de mantenimiento con actualización del número de versión.
  • Sin cambios funcionales respecto a la versión 1.0.3.
  • Garantiza la compatibilidad con las dependencias más recientes.

Cambios en la versión 1.0.3

  • Se añadió la nueva herramienta authenticate para permitir la reautenticación sin reiniciar Claude.
  • Se hizo posible cambiar entre diferentes cuentas de Google durante una sesión.
  • Se expuso la funcionalidad de autenticación a través de la interfaz MCP.
  • Se mejoró la experiencia del usuario al eliminar la necesidad de reiniciar para cambiar de cuenta.
  • Se añadió una opción de autenticación manual para entornos donde localhost no es accesible.
  • Se implementó una interfaz readline para introducir códigos de autorización manualmente.
  • Se añadió la variable de entorno USE_MANUAL_AUTH para habilitar la autenticación manual.
  • Se actualizó la dependencia zod a la versión más reciente (3.24.2).
  • Se mejoró la validación de esquemas con las últimas funciones de zod.
  • Se mejoró la estabilidad y seguridad del código.
  • Se corrigió el error "Invalid state parameter" durante la reautenticación.
  • Se modificó el servidor OAuth para iniciarse bajo demanda y apagarse después de la autenticación.
  • Se mejoró la gestión del ciclo de vida del servidor para prevenir conflictos de puertos.
  • Se mejoró el manejo de errores para el flujo de autenticación.

Cambios en la versión 1.0.2

  • Se corrigió la función updateEvent para preservar los datos de eventos existentes al realizar actualizaciones parciales.
  • Se añadió la función getEvent para obtener los datos de eventos existentes antes de actualizar.
  • Se modificó updateEvent para fusionar los datos de actualización con los datos existentes y evitar la pérdida de datos.
  • Se actualizó la validación de esquemas para que todos los campos sean opcionales en las solicitudes de actualización.
  • Se mejoró la documentación de la función updateEvent.

Cambios en la versión 1.0.1

  • Se corrigió un problema de compatibilidad con Node.js v20.9.0+ y el paquete 'open' (v10+).
  • Se reemplazó la importación estática por una importación dinámica para el paquete 'open' solo ESM.
  • Se mejoró el manejo de errores al abrir el navegador durante la autenticación OAuth.
  • Se mejoraron los comentarios del código para un mejor mantenimiento.

Cambios en la versión 1.0.0

  • Versión principal que marca la preparación para producción.
  • Refactorización integral del código para mejorar el mantenimiento.
  • Internacionalización de todos los mensajes y comentarios (traducido del japonés al inglés).
  • Mejora de la consistencia y legibilidad del código.
  • Mejora de los mensajes de error para una mejor experiencia de usuario.
  • Documentación actualizada para reflejar el estado actual del proyecto.
  • Estilo de codificación estandarizado en todo el código base.

Cambios en la versión 0.8.0

  • Se mejoró el flujo de autenticación OAuth para manejar problemas con los tokens de actualización.
  • Se añadió el parámetro prompt: 'consent' para forzar a Google a mostrar la pantalla de consentimiento y proporcionar un nuevo token de actualización.
  • Se modificó el flujo de autenticación para funcionar solo con un token de acceso si no hay un token de actualización disponible.
  • Se mejoró la lógica de renovación de tokens para manejar casos donde no hay token de actualización o si el token de actualización no es válido.
  • Se actualizó el almacenamiento de tokens para guardar los tokens de acceso renovados para una mejor gestión de tokens.
  • Se corrigió un posible bucle infinito en la lógica de renovación de tokens.

Instalación

Inicio rápido (Recomendado)

Instale directamente desde npm:

npm install -g @takumi0706/google-calendar-mcp

Instalación manual

Para desarrollo o personalización:

# Clone the repository
git clone https://github.com/takumi0706/google-calendar-mcp.git
cd google-calendar-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start

Despliegue en producción

Para uso en producción, el servidor requiere credenciales OAuth de Google válidas. El servidor no se iniciará sin las credenciales adecuadas, garantizando el cumplimiento de seguridad.

Pruebas

Para ejecutar las pruebas:

# Run all tests
npm test

# Run tests with coverage report
npm test -- --coverage

Licencia

MIT