Google Calendar MCP Server

Servidor MCP de Google Calendar

AVISO DE ACTUALIZACIÓN DE VERSIÓN
La versión 1.0.5 añade compatibilidad con eventos recurrentes mediante el parámetro recurrence en las herramientas createEvent y updateEvent . Esto permite crear y modificar eventos recurrentes directamente sin tener que configurarlos manualmente tras su creación.

Descripción general 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, ofreciendo la posibilidad de mostrar, crear, actualizar y eliminar eventos del calendario mediante interacción con lenguaje natural.

Características principales

• Integración de Google Calendar : proporciona un puente entre Claude Desktop y la API de Google Calendar
• Implementación de MCP : sigue la especificación del Protocolo de contexto de modelo para la integración de herramientas de asistente 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 integrales de eventos de calendario (obtener, crear, actualizar, eliminar)
• Compatibilidad de color : 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 de MCP : utiliza @modelcontextprotocol/sdk para la integración con Claude Desktop
• API de Google : utiliza googleapis para acceder a la API de Google Calendar
• Zod : Implementa la validación del esquema para datos de solicitud/respuesta
• Configuración basada en el entorno : utiliza dotenv para la gestión de la configuración
• Helmet.js : Para encabezados de seguridad
• AES-256-GCM : para cifrado de tokens
• Jest : para pruebas unitarias y cobertura
• Acciones de GitHub : para CI/CD

Componentes principales

1. Servidor MCP : implementación del servidor central que maneja la comunicación con Claude Desktop
2. Herramientas de Google Calendar : Operaciones de calendario (recuperación, creación, actualización, eliminación)
3. Controlador de autenticación : gestión del flujo OAuth2 con la API de Google
4. Validación de esquemas : garantizar la integridad de los datos en todas las operaciones
5. Token Manager : gestión segura de tokens de autenticación

Herramientas disponibles

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

1. obtenerEventos

Recupera eventos del calendario con varias opciones de filtrado.

Parámetros:

• calendarId (opcional): ID del calendario (usa el calendario principal si se omite)
• timeMin (opcional): Hora de inicio para la recuperación del evento (formato ISO 8601, p. ej., "2025-03-01T00:00:00Z")
• timeMax (opcional): Hora de finalización para la recuperación del evento (formato ISO 8601)
• maxResults (opcional): Número máximo de eventos a recuperar (predeterminado: 10)
• orderBy (opcional): orden de clasificación ("startTime" o "updated")

2. crearEvento

Crea un nuevo evento de calendario.

Parámetros:

• calendarId (opcional): ID del calendario (usa 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 tiempo 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 todo el día
    • timeZone (opcional): zona horaria (p. ej., "Asia/Tokio")
  • end : objeto de hora de finalización (mismo formato que inicio)
  • attendees (opcional): Matriz de asistentes con correo electrónico y nombre para mostrar opcional
  • colorId (opcional): ID de color del evento (1-11)
  • recurrence (opcional): Matriz de reglas de recurrencia en formato RFC5545 (por ejemplo, ["RRULE=WEEKLY;BYDAY=MO,WE,FR"])

3. actualizaciónEvento

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

Parámetros:

• calendarId (opcional): ID del calendario (usa 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 (la misma estructura que createEvent, todos los campos son opcionales)
  • Sólo se actualizarán los campos que se proporcionen explícitamente
  • Los campos no incluidos en la solicitud de actualización conservarán sus valores existentes
  • Esto permite realizar actualizaciones parciales sin perder datos.
  • El parámetro recurrence se puede actualizar para modificar patrones de eventos recurrentes

4. eliminarEvento

Elimina un evento del calendario.

Parámetros:

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

5. autenticar

Se vuelve a autenticar con Google Calendar. Esto es útil si quieres cambiar entre diferentes cuentas de Google sin tener que reiniciar Claude.

Parámetros:

• Ninguno

Directrices de desarrollo

Al añadir nuevas funciones, modificar código o corregir errores, incremente semánticamente la versión con cada cambio mediante el comando npm version . Además, asegúrese de que su código sea claro y cumpla con todas las reglas de codificación necesarias, como la programación orientada a objetos. El script de versión ejecutará automáticamente npm install cuando se actualice la versión, pero aun así debe compilar, ejecutar lint y probar su código antes de enviarlo.

Estructura del código

• src/ : Directorio del código fuente
  • auth/ : Manejo de autenticación
  • config/ : Ajustes de configuración
  • mcp/ : Implementación del servidor MCP
  • herramientas/ : Implementaciones de herramientas de Google Calendar
  • utils/ : Funciones de utilidad y ayudantes

Mejores prácticas

• Escritura correcta según las mejores prácticas de TypeScript
• Mantener un manejo integral de errores
• Garantizar un flujo de autenticación adecuado
• Mantenga las dependencias actualizadas
• Redactar documentación clara para todas las funciones.
• Implementar las mejores prácticas de seguridad
• Siga los estándares de autenticación OAuth 2.1
• Utilice la validación del esquema para todos los datos de entrada/salida

Pruebas

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

Despliegue

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

Prerrequisitos

1. Cree un proyecto de Google Cloud y habilite la API de Google Calendar
2. Configurar las credenciales de OAuth2 en Google Cloud Console
3. Configurar variables de entorno:

Configuración del escritorio de Claude

Añade el servidor a tu claude_desktop_config.json . Si estás trabajando en un entorno donde no se puede acceder a localhost, añade la variable de entorno USE_MANUAL_AUTH con el valor "true".

Consideraciones de seguridad

• Los tokens OAuth se almacenan únicamente en la memoria (no se almacenan en un almacenamiento basado en archivos)
• Las credenciales confidenciales deben proporcionarse como variables de entorno
• Cifrado de tokens mediante AES-256-GCM para almacenamiento seguro
• Implementación de PKCE con generación explícita de code_verifier y code_challenge
• Validación de parámetros de estado para la protección CSRF
• Encabezados de seguridad aplicados mediante Helmet.js
• Limitación de velocidad para la protección de puntos finales de API
• Validación de entrada con el esquema Zod

Para obtener más detalles, consulte SECURITY.md .

Mantenimiento

• Actualizaciones periódicas para mantener la compatibilidad con la API de Google Calendar
• Las actualizaciones de versiones están documentadas en README.md

Solución de problemas

Si encuentra algún problema:

1. Asegúrese de que sus credenciales de Google OAuth estén configuradas correctamente
2. Asegúrese de tener permisos suficientes para acceder a la API de Google Calendar
3. Verifique que la configuración de Claude Desktop sea correcta

Errores comunes

• Errores de análisis de JSON : Si ve errores como Unexpected non-whitespace character after JSON at position 4 (line 1 column 5) , suele deberse a mensajes JSON-RPC mal formados. Este problema se ha solucionado en la versión 0.6.7 y posteriores. Si persiste, actualice a la última versión.
• Errores de autenticación : Verifique sus credenciales de Google OAuth
• Parámetro de estado no válido : Si al volver a autenticarse ve Authentication failed: Invalid state parameter , actualice 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 deba cerrar el puerto 4153 y reiniciar la aplicación.
• Errores de conexión : asegúrese de que solo se esté ejecutando una instancia del servidor
• Problemas de desconexión : asegúrese de que su servidor esté manejando correctamente los mensajes MCP sin sockets TCP personalizados
• No se puede acceder a localhost : Si ejecuta la aplicación en un entorno donde no se puede acceder a localhost (como un servidor remoto o un contenedor), habilite la autenticación manual configurando USE_MANUAL_AUTH=true . Esto le permitirá ingresar manualmente el código de autorización que muestra Google después de autorizar la aplicación.

Historial de versiones

Cambios de la versión 1.0.6

• Se solucionó el problema de que el alcance no es necesario en este servidor MCP del calendario de Google.

Cambios de la versión 1.0.5

• Se agregó soporte para eventos recurrentes a través del 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 de la versión 1.0.4

• Versión de mantenimiento con actualización del número de versión
• Sin cambios funcionales desde la versión 1.0.3
• Garantiza la compatibilidad con las últimas dependencias.

Cambios de la versión 1.0.3

• Se agregó una nueva herramienta authenticate para permitir la reautenticación sin reiniciar Claude
• Se hizo posible cambiar entre diferentes cuentas de Google durante una sesión
• Funcionalidad de autenticación expuesta a través de la interfaz MCP
• Experiencia de usuario mejorada al eliminar la necesidad de reiniciar para cambiar de cuenta
• Se agregó la opción de autenticación manual para entornos donde no se puede acceder al host local
• Se implementó la interfaz readline para ingresar códigos de autorización manualmente
• Se agregó la variable de entorno USE_MANUAL_AUTH para habilitar la autenticación manual
• Dependencia de zod actualizada a la última versión (3.24.2)
• Validación de esquema mejorada con las últimas funciones de zod
• Mayor estabilidad y seguridad del código
• Se corrigió el error "Parámetro de estado no válido" durante la reautenticación.
• Servidor OAuth modificado para iniciarse a pedido y apagarse después de la autenticación
• Gestión mejorada del ciclo de vida del servidor para evitar conflictos de puertos
• Manejo mejorado de errores para el flujo de autenticación

Cambios de la versión 1.0.2

• Se corrigió la función updateEvent para preservar los datos de eventos existentes al realizar actualizaciones parciales
• Se agregó la función getEvent para obtener datos de eventos existentes antes de actualizar
• Se modificó updateEvent para fusionar los datos de actualización con los datos existentes para evitar la pérdida de datos.
• Se actualizó la validación del esquema para que todos los campos sean opcionales en las solicitudes de actualización
• Documentación mejorada para la función updateEvent

Cambios de la versión 1.0.1

• Se solucionó el problema de compatibilidad con Node.js v20.9.0+ y el paquete 'open' (v10+)
• Se reemplazó la importación estática con la importación dinámica para el paquete "abierto" exclusivo de ESM
• Manejo de errores mejorado al abrir el navegador durante la autenticación OAuth
• Comentarios de código mejorados para un mejor mantenimiento

Cambios de la versión 1.0.0

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

Cambios de la versión 0.8.0

• Flujo de autenticación OAuth mejorado para gestionar problemas de token de actualización
• Se agregó prompt: 'consent' para obligar a Google a mostrar la pantalla de consentimiento y proporcionar un nuevo token de actualización.
• Flujo de autenticación modificado para funcionar solo con un token de acceso si no hay un token de actualización disponible
• Lógica de actualización de token mejorada para manejar casos en los que no hay un token de actualización o si el token de actualización no es válido
• Almacenamiento de tokens actualizado para guardar tokens de acceso actualizados para una mejor gestión de tokens
• Se solucionó un posible bucle infinito en la lógica de actualización del token.

Desarrollo

Para contribuir a este proyecto:

Pruebas

Para ejecutar las pruebas:

Licencia

Instituto Tecnológico de Massachusetts (MIT)