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 y gestionar eventos de calendario mediante una interfaz estandarizada.

Características

• Lista de calendarios disponibles
• Enumerar eventos de un calendario
• Crear nuevos eventos de calendario
• Actualizar eventos existentes
• Eliminar eventos
• Procesar eventos a partir de capturas de pantalla e imágenes

Requisitos

1. Node.js 16 o superior
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)

Estructura del proyecto

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
   • Seleccione "Aplicación de escritorio" como tipo de aplicación
   • 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.

Instalación

1. Clonar el repositorio
2. Instalar dependencias:
   npm install
3. Construya el código TypeScript:
   npm run build
4. 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.

Scripts disponibles

• npm run build : compila el código TypeScript
• npm run build:watch : compila TypeScript en modo de vigilancia para desarrollo
• npm run dev : inicia el servidor en modo de desarrollo usando ts-node
• npm run auth : inicia el servidor de autenticación para el flujo de Google OAuth

Autenticación

El servidor admite flujos de autenticación tanto automáticos como manuales:

Autenticación automática (recomendada)

1. Coloque sus credenciales de Google OAuth en un archivo llamado gcp-oauth.keys.json en el directorio raíz del proyecto.
2. Inicie el servidor MCP:
   npm start
3. Si no se encuentran tokens de autenticación válidos, el servidor automáticamente:
   • Iniciar un servidor de autenticación (en los puertos 3000-3004)
   • Abra una ventana del navegador para el flujo OAuth
   • Guarde los tokens de forma segura una vez autenticados
   • Apagar el servidor de autenticación
   • Continuar con el funcionamiento normal del servidor MCP

El servidor administra automáticamente la actualización del token y la re-autenticación cuando sea necesario:

• Los tokens se actualizan automáticamente antes de su vencimiento.
• Si la actualización falla, los mensajes de error claros lo guiarán a través de la reautenticación
• Los archivos de token se almacenan de forma segura con permisos restringidos

Autenticación manual

Para usuarios avanzados o para solucionar problemas, puede ejecutar manualmente el flujo de autenticación:

Esto hará lo siguiente:

1. Iniciar el servidor de autenticación
2. Abra una ventana del navegador para el flujo OAuth
3. Guarde los tokens y salga

Notas de seguridad

• Las credenciales de OAuth se almacenan en gcp-oauth.keys.json
• Los tokens de autenticación se almacenan en .gcp-saved-tokens.json con 600 permisos
• Los tokens se actualizan automáticamente en segundo plano.
• La integridad del token se valida antes de cada llamada a la API
• El servidor de autenticación se apaga automáticamente después de una autenticación exitosa
• Nunca envíe credenciales OAuth ni archivos de token al control de versiones

Uso

El servidor expone las siguientes herramientas:

• list-calendars : Lista todos los calendarios disponibles
• list-events : enumera eventos de un calendario
• create-event : Crea un nuevo evento de calendario
• update-event : Actualizar un evento de calendario existente
• delete-event : Eliminar un evento del calendario

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": ["path/to/build/index.js"] } } }
2. Reiniciar Claude Desktop

Ejemplo de uso

Además de las capacidades normales que esperaría de una integración de calendario, también puede hacer cosas realmente dinámicas como agregar eventos desde capturas de pantalla e imágenes y mucho más.

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. Comprobar asistencia:
   Which events tomorrow have attendees who have not accepted the invitation?
3. Coordinar automáticamente eventos:
   Here's some available that was provided to me by someone I am interviewing. Take a look at the available times and create an event for me to interview them that is free on my work calendar.
4. 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

Desarrollo

Solución de problemas

Problemas comunes y soluciones:

1. El token OAuth caduca después de una semana (7 días)
   • Las aplicaciones que están en modo de prueba, en lugar de producción, deberán pasar por el flujo OAuth nuevamente después de una semana.
2. Errores de token OAuth
   • Asegúrese de que su gcp-oauth.keys.json tenga el formato correcto
   • Intente eliminar .gcp-saved-tokens.json y volver a autenticarse
3. Errores de compilación de TypeScript
   • Asegúrese de que todas las dependencias estén instaladas: npm install
   • Comprueba que tu versión de Node.js coincida con los requisitos previos
   • Limpiar el directorio de compilación: rm -rf build/
4. Problemas de procesamiento de imágenes
   • Verifique que el formato de imagen sea compatible
   • Asegúrese de que la imagen contenga texto claro y legible.

Notas de seguridad

• El servidor se ejecuta localmente y requiere autenticación OAuth
• Las credenciales de OAuth deben almacenarse en gcp-oauth.keys.json en la raíz del proyecto
• Los tokens de autenticación se almacenan en .gcp-saved-tokens.json con permisos de archivo restringidos
• Los tokens se actualizan automáticamente cuando caducan
• Nunca envíe sus credenciales OAuth ni sus archivos de token al control de versiones
• Para uso en producción, haga que Google verifique su aplicación OAuth

Licencia

Instituto Tecnológico de Massachusetts (MIT)