Google Calendar

Se integra con Google Calendar para leer, crear, actualizar y buscar eventos del calendario.

Documentación

Servidor MCP de Google Calendar

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona integración con Google Calendar para asistentes de IA como Claude.

Construí Cocal como un asistente de calendario alojado por separado, llevando este proyecto más allá con un calendario visual completo dentro de tu chat con Claude. Conecta tus cuentas de Google sin crear un proyecto de Google Cloud ni ejecutar un servidor.

Planifica entre cuentas. Verifica disponibilidad y detecta conflictos entre tus calendarios de trabajo, personales y compartidos de Google en una sola conversación.
Úsalo en escritorio y móvil. Consulta y gestiona tus calendarios en Claude en web, escritorio, iOS y Android.
Lleva tus preferencias a nuevos chats. Guarda reglas como "no reuniones antes de las 10" o qué calendario usar para planes personales.

_{Interfaz real de Cocal con datos de calendario de muestra. Haz clic en cualquier captura para ampliarla.}

Prueba Cocal →

Características

Soporte Multi-Cuenta: Conecta múltiples cuentas de Google (por ejemplo, trabajo, personal) y consúltalas simultáneamente
Soporte Multi-Calendario: Lista eventos de múltiples calendarios en una sola solicitud
Conflictos Entre Cuentas: Detecta eventos superpuestos en cualquier combinación de calendarios
Gestión de Eventos: Crea, actualiza, elimina y busca eventos de calendario
Eventos Recurrentes: Capacidades avanzadas de modificación para eventos recurrentes
Consultas de Disponibilidad: Verifica disponibilidad entre calendarios
Programación Inteligente: Comprensión de lenguaje natural para fechas y horas
Importación Inteligente: Agrega eventos de calendario desde imágenes, PDFs o enlaces web

Inicio Rápido

Requisitos Previos

Un proyecto de Google Cloud con la API de Calendar habilitada
Credenciales OAuth 2.0 (tipo Aplicación de escritorio)

Configuración de Google Cloud

Ve a la Consola de Google Cloud
Crea un nuevo proyecto o selecciona uno existente.
Habilita la API de Google Calendar para tu proyecto. Asegúrate de que el proyecto correcto esté seleccionado en la barra superior antes de habilitar la API.
Crea credenciales OAuth 2.0:
- Ve a Credenciales
- Haz clic en "Crear credenciales" > "ID de cliente OAuth"
- Elige "Datos de usuario" para el tipo de datos a los que accederá la aplicación
- Agrega el nombre de tu aplicación e información de contacto
- Agrega los siguientes alcances (opcional):
  - https://www.googleapis.com/auth/calendar.events y https://www.googleapis.com/auth/calendar
- Selecciona "Aplicación de escritorio" como tipo de aplicación (¡Importante!)
- Guarda la clave de autenticación; necesitarás agregar su ruta al JSON en el siguiente paso
- Agrega tu dirección de correo electrónico como usuario de prueba en la pantalla de Audiencia
  - Nota: puede tomar unos minutos para que el usuario de prueba sea agregado. El consentimiento de OAuth no te permitirá continuar hasta que el usuario de prueba se haya propagado.
  - Nota sobre el modo de prueba: Mientras una aplicación está en modo de prueba, los tokens de autenticación expirarán después de 1 semana y deberán renovarse (consulta la sección de Re-autenticación a continuación).

Instalación

Opción 1: Usar con npx (Recomendado)

Agrega a tu configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["@cocal/google-calendar-mcp"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
      }
    }
  }
}

⚠️ Nota importante para usuarios de npx: Al usar npx, debes especificar la ruta del archivo de credenciales usando la variable de entorno GOOGLE_OAUTH_CREDENTIALS.

Opción 2: Instalación Local

git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
npm install
npm run build

Luego agrega a la configuración de Claude Desktop usando la ruta local o especificando la ruta con la variable de entorno GOOGLE_OAUTH_CREDENTIALS.

Opción 3: Instalación con Docker

git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
cp /path/to/your/gcp-oauth.keys.json .
docker compose up

Consulta la guía de implementación con Docker para opciones de configuración detalladas, incluido el modo de transporte HTTP.

Primera Ejecución

Inicia Claude Desktop
Pídele a Claude que se autentique con el servidor MCP de Google Calendar (por ejemplo, "Autentícate con Google Calendar"). Este paso es necesario antes de usar cualquier herramienta de calendario; sin él, las solicitudes fallarán con un error de -32600.
Completa el flujo de OAuth en tu navegador
¡Estás listo para usar las funciones de calendario!

¿Usas Claude Code? Se aplican los mismos pasos: solo pídele a Claude que se autentique con el servidor MCP de Google Calendar desde tu sesión de CLI antes de usar cualquier herramienta de calendario.

Re-autenticación

Si estás en modo de prueba (predeterminado), los tokens expiran después de 7 días. Si usas un cliente como Claude Desktop, debería abrir una ventana del navegador para re-autenticarse automáticamente. Sin embargo, si ves errores de autenticación, también puedes resolverlos siguiendo estos pasos:

Para usuarios de npx:

export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/gcp-oauth.keys.json"
npx @cocal/google-calendar-mcp auth

Para instalación local:

npm run auth

Para evitar la re-autenticación semanal, publica tu aplicación en modo de producción (sin verificación):

Ve a Consola de Google Cloud → "APIs y servicios" → "Pantalla de consentimiento de OAuth"
Haz clic en "PUBLICAR APLICACIÓN" y confirma
Tus tokens ya no expirarán después de 7 días, pero Google mostrará una advertencia sobre que la aplicación no está verificada.

Consulta la Guía de autenticación para más detalles.

Autenticación con Cuenta de Servicio (opcional)

Una cuenta de servicio tiene su propia clave de larga duración, por lo que no hay paso de consentimiento en el navegador ni token de actualización que expire. Esta es la alternativa a publicar tu aplicación OAuth cuando la re-autenticación semanal anterior no sea práctica: servidores sin interfaz gráfica, contenedores, CI o una aplicación que prefieras dejar en estado de Pruebas.

Para qué calendarios funciona esto

Calendario	¿Funciona?	Cómo se otorga el acceso
Calendario personal `@gmail.com`	Sí	Comparte el calendario con la dirección de correo electrónico de la cuenta de servicio
Calendario de Google Workspace	Sí	Compártelo o usa la delegación de todo el dominio para suplantar a un usuario
Cualquier calendario compartido contigo por otra persona	No	El propietario debe compartirlo directamente con la cuenta de servicio

Compartir es lo que otorga el acceso: la cuenta de servicio es una identidad separada y no ve nada por defecto. La delegación de todo el dominio no es necesaria para el caso del calendario personal; solo se necesita si quieres que la cuenta de servicio actúe como un usuario.

Limitaciones

No se puede invitar a asistentes. La API rechaza esto con "Las cuentas de servicio no pueden invitar asistentes sin Delegación de Autoridad de Todo el Dominio". Todo lo demás (crear, actualizar, eliminar, buscar, disponibilidad) funciona normalmente.
calendarId debe ser explícito. primary se refiere al calendario propio y vacío de la cuenta de servicio; pasa la dirección del calendario (por ejemplo, you@gmail.com) en su lugar.
list-calendars no devuelve nada. Un calendario compartido con una cuenta de servicio no aparece en su calendarList a menos que se agregue explícitamente. Dirígete a los calendarios por id.

Configuración

Crea una cuenta de servicio y una clave JSON en tu proyecto de Google Cloud:

gcloud iam service-accounts create calendar-mcp --project=YOUR_PROJECT
gcloud iam service-accounts keys create service-account.json \
  --iam-account=calendar-mcp@YOUR_PROJECT.iam.gserviceaccount.com

En Google Calendar, abre Configuración → tu calendario → Compartir con personas específicas, agrega el correo electrónico de la cuenta de servicio y otorga "Realizar cambios en eventos".

Apunta el servidor a la clave:

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["@cocal/google-calendar-mcp"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY": "/path/to/service-account.json"
      }
    }
  }
}

La clave se detecta por su contenido ("type": "service_account"), no por una bandera de modo, por lo que cambiar una instalación existente es un cambio de un solo archivo. Se consultan tres cosas, y la primera que produzca una respuesta gana:

GOOGLE_SERVICE_ACCOUNT_KEY — una demanda explícita del modo de cuenta de servicio. Si ese archivo falta, no se puede leer o no es una clave de cuenta de servicio, el servidor falla al iniciar y lo indica, en lugar de recurrir a OAuth y dejarte adivinando por qué.
El archivo de credenciales propio de este servidor — GOOGLE_OAUTH_CREDENTIALS si lo configuras, de lo contrario gcp-oauth.keys.json. Se lee por contenido, por lo que poner una clave de cuenta de servicio en esa ruta funciona. Si contiene credenciales normales de cliente OAuth, eso lo resuelve: tienes una configuración OAuth y se omite el paso 3.
GOOGLE_APPLICATION_CREDENTIALS — la variable compartida de Google, a menudo ya configurada para herramientas no relacionadas. Solo se consulta cuando este servidor no tiene su propio archivo de credenciales, por lo que nunca puede cambiar silenciosamente una instalación OAuth que funciona a una cuenta de servicio en el próximo reinicio. Un problema con ella se advierte, nunca es fatal.

El servidor registra qué credenciales eligió y de dónde provienen en cada inicio. Configura GOOGLE_SERVICE_ACCOUNT_SUBJECT solo si usas delegación de todo el dominio.

Trata el archivo de clave como una credencial: no expira. chmod 600 él, mantenlo fuera del control de versiones y elimina la clave en la Consola de Cloud si alguna vez se expone.

Gestión de Múltiples Cuentas

Conecta múltiples cuentas de Google y úsalas simultáneamente.

En el chat (recomendado): Usa la herramienta manage-accounts para agregar, listar o eliminar cuentas directamente desde tu asistente de IA: no se necesita terminal. Consulta la Guía de autenticación para más detalles.

CLI: Para la configuración inicial, usa npm run account auth <nickname> (por ejemplo, npm run account auth work).

HTTP / Docker: Visita http://localhost:3000/accounts para gestionar cuentas en el navegador.

Cuando no se proporciona el parámetro account a una herramienta, las herramientas de solo lectura combinan resultados de todas las cuentas, mientras que las herramientas de escritura seleccionan automáticamente la cuenta con los permisos apropiados.

Ejemplo de Uso

Además de las capacidades normales que esperarías de una integración de calendario, también puedes realizar procesos realmente dinámicos y de múltiples pasos como:

Disponibilidad entre calendarios:

Please provide availability looking at both my personal and work calendar for this upcoming week.
I am looking for a good time to meet with someone in London for 1 hr.

Agregar eventos desde capturas de pantalla, imágenes y otras fuentes de datos:
```
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

Análisis de calendario:

What events do I have coming up this week that aren't part of my usual routine?

Verificar asistencia:

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

Responder a invitaciones:

Accept the team meeting invitation on my calendar for tomorrow at 2pm

Rechazar con una nota:

Decline the Friday meeting with a note that I have a scheduling conflict

Responder a eventos recurrentes:

Accept just this week's standup, but keep future instances as tentative

Decline all future Monday planning meetings

Coordinar eventos automáticamente:

Here's some availability that was provided to me by someone. {available times}
Take a look at the times provided and let me know which ones are open on my calendar.

Herramientas Disponibles

Herramienta	Descripción
`list-calendars`	Lista todos los calendarios disponibles
`list-events`	Lista eventos con filtrado por fecha
`get-event`	Obtén detalles de un evento específico por ID
`search-events`	Busca eventos por consulta de texto
`create-event`	Crea nuevos eventos de calendario
`create-events`	Crea múltiples eventos en una sola llamada con valores predeterminados compartidos (omite la detección de conflictos)
`update-event`	Actualiza eventos existentes
`delete-event`	Elimina eventos
`respond-to-event`	Responde a invitaciones de eventos (Aceptar, Rechazar, Tal vez, Sin respuesta)
`get-freebusy`	Verifica disponibilidad entre calendarios, incluidos calendarios externos
`get-current-time`	Obtén la fecha y hora actuales en la zona horaria del calendario
`list-colors`	Lista los colores de eventos disponibles
`manage-accounts`	Agrega, lista o elimina cuentas de Google conectadas

Documentación

Configuración de autenticación - Configuración detallada de Google Cloud
Uso avanzado - Multi-cuenta, operaciones por lotes
Guía de implementación - Transporte HTTP, acceso remoto
Guía de Docker - Implementación con Docker en modos stdio y HTTP
Arquitectura - Resumen de la arquitectura técnica
Desarrollo - Contribución y pruebas
Pruebas - Guía de pruebas unitarias y de integración
Actualizaciones Multi-Cuenta - Estado actual y hoja de ruta para el soporte multi-cuenta

Patrocinio

Si Google Calendar MCP te ha sido útil y estás dispuesto, agradecería mucho que consideres patrocinar mi trabajo de código abierto. ¡Gracias! – Nate

Configuración

Variables de entorno:

Los indicadores de CLI tienen prioridad sobre las variables de entorno. Los valores malformados (por ejemplo, un PORT no numérico o un TRANSPORT desconocido) detienen el servidor al inicio con un error, y la configuración resuelta se registra en stderr al inicio.

Variable	Indicador de CLI	Predeterminado	Descripción
`GOOGLE_OAUTH_CREDENTIALS`		`gcp-oauth.keys.json` en la raíz del paquete	Ruta al archivo de credenciales OAuth
`GOOGLE_SERVICE_ACCOUNT_KEY`		sin establecer	Ruta a un archivo de clave de cuenta de servicio explícito
`GOOGLE_APPLICATION_CREDENTIALS`		sin establecer	Archivo de credenciales ambientales de Google, utilizado cuando este servidor no tiene un archivo de credenciales OAuth
`GOOGLE_SERVICE_ACCOUNT_SUBJECT`		sin establecer	Usuario del espacio de trabajo a suplantar con delegación de dominio completo
`GOOGLE_CALENDAR_MCP_TOKEN_PATH`		`$XDG_CONFIG_HOME/google-calendar-mcp/tokens.json`	Ubicación de almacenamiento de tokens personalizada
`XDG_CONFIG_HOME`		`~/.config`	Directorio de configuración base para el almacenamiento de tokens (ignorado si GOOGLE_CALENDAR_MCP_TOKEN_PATH está establecido)
`GOOGLE_ACCOUNT_MODE`		`normal`	Apodo de cuenta utilizado para operaciones de cuenta única y el comando `auth`
`ENABLED_TOOLS`	`--enable-tools`	todas las herramientas	Lista separada por comas de herramientas a exponer (ver Filtrado de herramientas)
`TRANSPORT`	`--transport`	`stdio`	Tipo de transporte: `stdio` o `http`
`PORT`	`--port`	`3000`	Puerto de transporte HTTP (1-65535)
`HOST`	`--host`	`127.0.0.1`	Dirección de enlace del transporte HTTP
`DEBUG`	`--debug`	`false`	Reservado: `true` se acepta y se muestra en el registro de inicio, pero actualmente no habilita registro adicional
`NODE_ENV`		sin establecer	`test` omite la autenticación de inicio y utiliza el espacio de nombres de cuenta `test` (para el conjunto de pruebas)

Filtrado de herramientas

Puede limitar qué herramientas se exponen al asistente de IA utilizando el indicador --enable-tools o la variable de entorno ENABLED_TOOLS. Esto es útil para:

Reducir el uso de contexto: Cada herramienta consume tokens de la ventana de contexto de la IA. Limitar las herramientas puede ayudar a preservar el contexto para conversaciones más largas.
Seguridad: Restringir capacidades a operaciones de solo lectura o funcionalidades específicas.
Simplicidad: Solo exponer las herramientas que su flujo de trabajo realmente necesita.

Mediante línea de comandos:

npx @cocal/google-calendar-mcp start --enable-tools list-events,create-event,get-current-time

Mediante variable de entorno en la configuración de Claude Desktop:

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["@cocal/google-calendar-mcp"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/credentials.json",
        "ENABLED_TOOLS": "list-events,create-event,get-current-time,update-event"
      }
    }
  }
}

Nombres de herramientas disponibles: list-calendars, list-events, search-events, get-event, list-colors, create-event, create-events, update-event, delete-event, get-freebusy, get-current-time, respond-to-event, manage-accounts

Nota: La herramienta manage-accounts siempre está disponible independientemente del filtrado, ya que es necesaria para la gestión de autenticación.

Cuando el filtrado de herramientas está activo, el servidor proporciona instrucciones al asistente de IA enumerando qué herramientas están deshabilitadas. Esto permite que la IA informe a los usuarios de que existe funcionalidad adicional pero que actualmente no está disponible, sin consumir el costo completo de tokens de esos esquemas de herramientas.

Si la lista está vacía o contiene solo comas, el servidor fallará al iniciar con un error.

Si se especifica un nombre de herramienta no válido, el servidor fallará al iniciar con un error que enumera todas las herramientas disponibles.

Seguridad

Los tokens OAuth se almacenan de forma segura en el directorio de configuración de su sistema
Las credenciales nunca salen de su máquina local
Todas las operaciones de calendario requieren consentimiento explícito del usuario

Solución de problemas

Archivo de credenciales OAuth no encontrado:
- Para usuarios de npx: Debe especificar la ruta del archivo de credenciales usando GOOGLE_OAUTH_CREDENTIALS
- Verifique que las rutas de archivo sean absolutas y accesibles
Errores de autenticación:
- Asegúrese de que su archivo de credenciales contenga credenciales para un tipo de Aplicación de escritorio
- Verifique que su correo de usuario esté agregado como Usuario de prueba en la pantalla de consentimiento OAuth de Google Cloud
- Intente eliminar los tokens guardados y volver a autenticarse
- Verifique que ningún otro proceso esté bloqueando los puertos 3500-3505
Errores de compilación:
- Ejecute npm install && npm run build nuevamente
- Verifique la versión de Node.js (use LTS)
- Elimine el directorio build/ y ejecute npm run build
Pantalla de "Algo salió mal" durante la autenticación del navegador
- Ejecute el comando de autenticación manualmente (ver Re-autenticación arriba)
- Use un navegador basado en Chromium. La autenticación de aplicaciones de prueba puede no funcionar en algunos navegadores que no son Chromium.
Errores de "Límite de tasa de usuario excedido"
- Esto ocurre típicamente cuando sus credenciales OAuth carecen de información del proyecto
- Asegúrese de que su archivo gcp-oauth.keys.json incluya project_id
- Vuelva a descargar las credenciales desde Google Cloud Console si es necesario
- El archivo debe tener el formato: {"installed": {"project_id": "your-project-id", ...}}

Licencia

MIT

Google Calendar

Documentación

Servidor MCP de Google Calendar

Características

Inicio Rápido

Requisitos Previos

Configuración de Google Cloud

Instalación

Primera Ejecución

Re-autenticación

Autenticación con Cuenta de Servicio (opcional)

Para qué calendarios funciona esto

Limitaciones

Configuración

Gestión de Múltiples Cuentas

Ejemplo de Uso

Herramientas Disponibles

Documentación

Patrocinio

Configuración

Filtrado de herramientas

Seguridad

Solución de problemas

Licencia

Soporte