Google Calendar

Un servidor MCP para Google Calendar, que permite a los LLMs leer, crear y gestionar eventos del calendario.

GitHub
1
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Google Calendar

Este es un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona integración con Google Calendar. Permite a los LLMs leer, crear y gestionar eventos de calendario a través de una interfaz estandarizada.

Características

  • Listar calendarios disponibles
  • Listar 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 Calendar habilitada
  4. Credenciales OAuth 2.0 (ID de cliente y secreto de cliente)

Estructura del Proyecto

google-calendar-mcp/
├── src/           # TypeScript source files
├── build/         # Compiled JavaScript output
├── llm/           # LLM-specific configurations and prompts
├── package.json   # Project dependencies and scripts
└── tsconfig.json  # TypeScript configuration

Configuración de Google Cloud

  1. Vaya a la Consola de Google Cloud
  2. Cree un nuevo proyecto o seleccione uno existente.
  3. Habilite la API de Google Calendar para su proyecto. Asegúrese de que el proyecto correcto esté seleccionado en la barra superior antes de habilitar la API.
  4. Cree credenciales OAuth 2.0:
    • Vaya a Credenciales
    • Haga clic en "Crear credenciales" > "ID de cliente OAuth"
    • Elija "Datos de usuario" para el tipo de datos a los que la aplicación accederá
    • Agregue el nombre de su aplicación e 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 OAuth
      • Nota: tomará unos minutos para que el usuario de prueba sea agregado. El consentimiento OAuth no le permitirá continuar hasta que el usuario de prueba se haya propagado.

Instalación

  1. Clone el repositorio
  2. Instale las dependencias: 
    npm install
  3. Compile el código TypeScript: 
    npm run build
  4. Descargue sus credenciales OAuth de Google desde la Consola de Google Cloud (en "Credenciales") y renombre el archivo a gcp-oauth.keys.json y colóquelo en el directorio raíz del proyecto.

Scripts Disponibles

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

Autenticación

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

Autenticación Automática (Recomendada)

  1. Coloque sus credenciales OAuth de Google 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)
    • Abrirá una ventana del navegador para el flujo OAuth
    • Guardará los tokens de forma segura una vez autenticado
    • Apagará el servidor de autenticación
    • Continuará con la operación normal del servidor MCP

El servidor gestiona automáticamente la renovación de tokens y la reautenticación cuando sea necesario:

  • Los tokens se renuevan automáticamente antes de su expiración
  • Si la renovación falla, mensajes de error claros lo guían a través de la reautenticación
  • Los archivos de tokens se almacenan de forma segura con permisos restringidos

Autenticación Manual

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

npm run auth

Esto:

  1. Iniciará el servidor de autenticación
  2. Abrirá una ventana del navegador para el flujo OAuth
  3. Guardará los tokens y saldrá

Notas de Seguridad

  • Las credenciales OAuth se almacenan en gcp-oauth.keys.json
  • Los tokens de autenticación se almacenan en .gcp-saved-tokens.json con permisos 600
  • Los tokens se renuevan automáticamente en segundo plano
  • La integridad de los tokens 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 o archivos de tokens al control de versiones

Uso

El servidor expone las siguientes herramientas:

  • list-calendars: Listar todos los calendarios disponibles
  • list-events: Listar eventos de un calendario
  • create-event: Crear un nuevo evento de calendario
  • update-event: Actualizar un evento de calendario existente
  • delete-event: Eliminar un evento de calendario

Uso con Claude Desktop

  1. Agregue esta configuración a su archivo de configuración de Claude Desktop. Ej. /Users/<user>/Library/Application Support/Claude/claude_desktop_config.json:

    {
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": ["path/to/build/index.js"]
    }
  }
}

  2. Reinicie 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 compatibles: PNG, JPEG, GIF Las imágenes pueden contener detalles del evento como fecha, hora, ubicación y descripción

  2. Verificar asistencia:

    Which events tomorrow have attendees who have not accepted the invitation?

  3. Coordinar eventos automáticamente:

    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 expira 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 esté correctamente formateado
    • Intente eliminar .gcp-saved-tokens.json y reautenticarse

  3. Errores de Compilación de TypeScript

    • Asegúrese de que todas las dependencias estén instaladas: npm install
    • Verifique que su versión de Node.js cumpla con los requisitos previos
    • Limpie 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 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 renuevan automáticamente cuando expiran
  • Nunca envíe sus credenciales OAuth o archivos de tokens al control de versiones
  • Para uso en producción, haga que su aplicación OAuth sea verificada por Google

Licencia

MIT