Google Calendar MCP

Servidor MCP de Google Calendar

Este es un servidor de Protocolo de Contexto de Modelo (MCP) que se integra con Google Calendar. Permite a los LLM leer, crear, actualizar y buscar eventos del calendario mediante una interfaz estandarizada.

Ejemplo de uso

Además de las capacidades normales que esperaría de una integración de calendario, también puede realizar procesos realmente dinámicos de varios pasos como:

1. Agregar eventos desde capturas de pantalla e imágenes:
   Add this event to my calendar based on the attached screenshot.
   Formatos de imagen admitidos: PNG, JPEG, GIF Las imágenes pueden contener detalles del evento, como fecha, hora, ubicación y descripción.
2. Análisis del calendario:
   What events do I have coming up this week that aren't part of my usual routine?
3. Comprobar asistencia:
   Which events tomorrow have attendees who have not accepted the invitation?
4. Coordinar automáticamente eventos:
   Here's some available that was provided to me by someone. Take a look at the available times and create an event that is free on my work calendar.
5. Proporcione su propia disponibilidad:
   Please provide availability looking at both my personal and work calendar for this upcoming week. Choose times that work well for normal working hours on the East Coast. Meeting time is 1 hour

Requisitos

1. Node.js (se recomienda la última versión LTS)
2. TypeScript 5.3 o superior
3. Un proyecto de Google Cloud con la API de Calendario habilitada
4. Credenciales de OAuth 2.0 (ID de cliente y secreto de cliente)

Configuración de Google Cloud

1. Vaya a la consola de Google Cloud
2. Crea un nuevo proyecto o selecciona uno existente.
3. Habilite la API de Google Calendar para su proyecto. Asegúrese de seleccionar el proyecto correcto en la barra superior antes de habilitar la API.
4. Crear credenciales OAuth 2.0:
   • Ir a Credenciales
   • Haga clic en "Crear credenciales" > "ID de cliente OAuth".
   • Seleccione "Datos del usuario" para el tipo de datos a los que accederá la aplicación.
   • Añade el nombre de tu aplicación y tu información de contacto
   • Agregue los siguientes alcances (opcional):
     • https://www.googleapis.com/auth/calendar.events (o más amplio https://www.googleapis.com/auth/calendar si es necesario)
   • Seleccione “Aplicación de escritorio” como tipo de aplicación (¡Importante!)
   • Agregue su dirección de correo electrónico como usuario de prueba en la pantalla de consentimiento de OAuth
     • Nota: El usuario de prueba tardará unos minutos en añadirse. El consentimiento de OAuth no le permitirá continuar hasta que se haya propagado.
     • Nota sobre el modo de prueba: mientras una aplicación está en modo de prueba, los tokens de autenticación caducarán después de 1 semana y deberán actualizarse ejecutando npm run auth .

Instalación

1. Clonar el repositorio
2. Instalar dependencias (esto también compila el js mediante postinstall):
   npm install
3. Descargue sus credenciales de Google OAuth desde Google Cloud Console (en "Credenciales") y cambie el nombre del archivo a gcp-oauth.keys.json y colóquelo en el directorio raíz del proyecto.
   • Asegúrese de que el archivo contenga las credenciales para una "aplicación de escritorio".
   • Como alternativa, copie el archivo de plantilla proporcionado: cp gcp-oauth.keys.example.json gcp-oauth.keys.json y complételo con sus credenciales desde Google Cloud Console.

Scripts disponibles

• npm run build : compila el código TypeScript (compila src para build )
• npm run typecheck : ejecuta la comprobación de tipos de TypeScript sin compilar
• npm run start : inicia el servidor MCP compilado (usando node build/index.js )
• npm run auth : ejecuta manualmente el flujo de autenticación de Google OAuth.
• npm test : ejecuta el conjunto de pruebas unitarias/de integración usando Vitest
• npm run test:watch - Ejecuta pruebas en modo de vigilancia
• npm run coverage : ejecuta pruebas y genera un informe de cobertura

Autenticación

El servidor maneja la autenticación Google OAuth 2.0 para acceder a los datos de su calendario.

Flujo de autenticación automática (durante el inicio del servidor)

1. Asegúrese de que gcp-oauth.keys.json tenga el nombre correcto y esté ubicado en la raíz del proyecto.
2. Inicie el servidor MCP: npm start .
3. El servidor verificará si existen tokens de autenticación válidos en .gcp-saved-tokens.json .
4. Si se encuentran tokens válidos, el servidor se inicia normalmente.
5. Si no se encuentran tokens válidos:
   • El servidor intenta iniciar un servidor web local temporal (probando los puertos 3000-3004).
   • Su navegador web predeterminado se abrirá automáticamente en la pantalla de inicio de sesión y consentimiento de la cuenta de Google.
   • Siga las instrucciones del navegador para autorizar la aplicación.
   • Tras la autorización exitosa, será redirigido a una página local (por ejemplo, http://localhost:3000/oauth2callback ).
   • Esta página mostrará un mensaje de éxito confirmando que los tokens se han guardado en .gcp-saved-tokens.json (y mostrará la ruta exacta del archivo).
   • El servidor de autenticación temporal se apaga automáticamente.
   • El servidor principal MCP continúa su proceso de inicio.

Flujo de autenticación manual

Si necesita volver a autenticarse o prefiere gestionar la autenticación por separado:

1. Ejecute el comando: npm run auth
2. Este script realiza el mismo flujo de autenticación basado en navegador descrito anteriormente.
3. Se abrirá tu navegador, lo autorizas y verás la página de éxito indicando dónde se guardaron los tokens.
4. El script saldrá automáticamente luego de una autenticación exitosa.

Gestión de tokens

• Los tokens de autenticación se almacenan en .gcp-saved-tokens.json en la raíz del proyecto.
• Este archivo se crea automáticamente y no debe comprometerse con el control de versiones (está incluido en .gitignore ).
• El servidor intenta actualizar automáticamente los tokens de acceso vencidos utilizando el token de actualización almacenado.
• Si el token de actualización caduca (por ejemplo, después de 7 días si la aplicación de Google Cloud está en modo de prueba) o se revoca, deberá volver a autenticarse utilizando el flujo automático (reiniciando el servidor) o el comando manual npm run auth .

Pruebas

Las pruebas unitarias y de integración se implementan utilizando Vitest .

• Ejecutar pruebas: npm test
• Ejecutar pruebas en modo de vigilancia: npm run test:watch
• Generar informe de cobertura: npm run coverage

Las pruebas simulan dependencias externas (API de Google, sistema de archivos) para garantizar pruebas aisladas de la lógica y los controladores del servidor.

Notas de seguridad

• El servidor se ejecuta localmente y requiere autenticación OAuth.
• Las credenciales de OAuth ( gcp-oauth.keys.json ) y los tokens guardados ( .gcp-saved-tokens.json ) nunca deben enviarse al control de versiones. Asegúrese de que se agreguen a su archivo .gitignore .
• Para uso en producción, considere que Google verifique su aplicación OAuth.

Uso con Claude Desktop

1. Agregue esta configuración a su archivo de configuración de Claude Desktop. Por ejemplo /Users/<user>/Library/Application Support/Claude/claude_desktop_config.json :
   { "mcpServers": { "google-calendar": { "command": "node", "args": ["<absolute-path-to-project-folder>/build/index.js"] } } }
   Nota: Reemplace <absolute-path-to-project-folder> con la ruta real al directorio de su proyecto.
2. Reiniciar Claude Desktop

Desarrollo

Solución de problemas

1. Errores de autenticación/Restablecimiento de conexión al devolver la llamada:
   • Asegúrese de que gcp-oauth.keys.json exista y contenga credenciales para un tipo de aplicación de escritorio .
   • Verifique que su correo electrónico de usuario se haya agregado como Usuario de prueba en la configuración de la pantalla de Consentimiento de Google Cloud OAuth (espere unos minutos para que se propaguen los cambios).
   • Intente eliminar .gcp-saved-tokens.json y volver a autenticarse ( npm run auth o restart npm start ).
   • Verifique que ningún otro proceso esté bloqueando los puertos 3000-3004 cuando se requiere autenticación.
2. Los tokens vencen semanalmente:
   • Si tu aplicación de Google Cloud está en modo de prueba , los tokens de actualización caducan a los 7 días. Vuelve a autenticarte cuando sea necesario.
   • Considere mover su aplicación a Producción en Google Cloud Console para obtener tokens de actualización de mayor duración (requiere verificación de Google).
3. Errores de compilación:
   • Ejecute npm install nuevamente.
   • Verifique la versión de Node.js (use LTS).
   • Elimina el directorio build/ y ejecuta npm run build .

Si eres un desarrollador que desea contribuir con este repositorio, echa un vistazo a Descripción general de la arquitectura antes de contribuir.

Licencia

Instituto Tecnológico de Massachusetts (MIT)