Servidor MCP de Google Calendar

AVISO DE ACTUALIZACIÓN DE VERSIÓN
La versión 1.0.2 incluye una corrección para la función updateEvent que conserva los datos de eventos existentes al realizar actualizaciones parciales. La versión 1.0.1 incluye una corrección para la compatibilidad de Node.js v20.9.0+ con el paquete "open", que ahora es exclusivo de ESM en la versión 10+. La versión 1.0.0 marca nuestra primera versión lista para producción con una refactorización e internacionalización de código integrales.

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)

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.

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

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

Agregue el servidor a su claude_desktop_config.json :

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
• Los registros se almacenan en el directorio de inicio del usuario ~/.google-calendar-mcp/logs/

Solución de problemas

Si encuentra algún problema:

1. Consulte los registros en su directorio de inicio en ~/.google-calendar-mcp/logs/
2. Asegúrese de que sus credenciales de Google OAuth estén configuradas correctamente
3. Asegúrese de tener permisos suficientes para acceder a la API de Google Calendar
4. 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
• 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

Historial de versiones

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)