mcp-google-calendar

Google Calendar MCP

Español | Русский

A1 Google Calendar MCP permite que una aplicación de IA gestione Google Calendar en lenguaje natural. Revisa tu semana, programa una reunión con invitados y un enlace de Google Meet, reprograma o cancela, encuentra un horario en el que todos estén libres y bloquea tiempo de Fuera de Oficina o de Enfoque.

Utiliza la API de Google Calendar con tu cuenta de Google. Distingue una serie recurrente completa de una ocurrencia individual y hace explícitos los límites de la API de Calendar en lugar de dar a entender que cualquier tarea de calendario es posible.

• 19 herramientas. Inspecciona calendarios, eventos y disponibilidad, crea y edita eventos, expande series recurrentes y bloquea Fuera de Oficina y Tiempo de Enfoque, además de seis para conectar tu cuenta de Google.
• Inicia sesión desde el chat. No hay que escribir un archivo de credenciales a mano: pide al asistente que se conecte, aprueba el acceso en el navegador y la siguiente solicitud funciona sin reiniciar. El secreto del cliente viaja como una ruta de archivo, nunca a través de la conversación.
• Nadie recibe correos por accidente. El valor predeterminado de la API de Calendar para invitaciones, cambios y cancelaciones es el silencio; los invitados reciben correo solo cuando lo solicitas mediante send_updates.
• Las escrituras nunca se reproducen. Después de un fallo ambiguo, el servidor no reintenta una escritura; un evento duplicado podría reenviar correos a todos los invitados.
• Ámbitos mínimos de Google. Utiliza calendar.events y calendar.readonly, sin el ámbito amplio calendar.

Comienza con una pregunta de solo lectura:

¿Qué hay en mi calendario esta semana? Señala cualquier reunión que se superponga.

Conectar el servidor · Explorar casos de uso · Abrir documentación técnica

Véalo funcionar en un minuto

Usted: ¿Cómo se ve mi jueves y cuándo estamos libres Anna y yo?

Asistente: Muestra los eventos del jueves y los espacios libres compartidos. No cambia nada.

Usted: Reserva una revisión de diseño de 45 minutos con Anna en el primer espacio libre, con un enlace de Google Meet.

Asistente: Muestra la hora propuesta, la lista de invitados y el enlace de Meet, y luego pide confirmación antes de crear el evento.

Usted: Confirmar.

Asistente: Crea el evento. Nadie recibe un correo a menos que le pidas que envíe invitaciones.

Contenido

• Inicio rápido
• Qué puedes pedirle que haga
• Cómo cambia un evento
• Qué puede cambiar
• Obtener acceso
• Configuración
• Datos, límites y trabajo en segundo plano
• Documentación técnica
• Soporte

Inicio rápido

Necesitas Node.js 20+, una cuenta de Google y credenciales OAuth de un proyecto de Google Cloud con la API de Google Calendar habilitada.

1. Prepara el acceso OAuth de Google.
2. Añade el servidor a tu aplicación de IA.
3. Haz la pregunta de solo lectura anterior.

codex mcp add google-calendar \
  --env GOOGLE_CALENDAR_CLIENT_ID=your_client_id \
  --env GOOGLE_CALENDAR_CLIENT_SECRET=your_client_secret \
  --env GOOGLE_CALENDAR_REFRESH_TOKEN=your_refresh_token \
  -- npx -y @a1-x-tech/mcp-google-calendar@latest

codex mcp list

claude mcp add \
  --env GOOGLE_CALENDAR_CLIENT_ID=your_client_id \
  --env GOOGLE_CALENDAR_CLIENT_SECRET=your_client_secret \
  --env GOOGLE_CALENDAR_REFRESH_TOKEN=your_refresh_token \
  --transport stdio --scope user google-calendar \
  -- npx -y @a1-x-tech/mcp-google-calendar@latest

claude mcp list

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-calendar@latest"],
      "env": {
        "GOOGLE_CALENDAR_CLIENT_ID": "your_client_id",
        "GOOGLE_CALENDAR_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_CALENDAR_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

{
  "mcpServers": {
    "google-calendar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-calendar@latest"],
      "env": {
        "GOOGLE_CALENDAR_CLIENT_ID": "your_client_id",
        "GOOGLE_CALENDAR_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_CALENDAR_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

{
  "servers": {
    "google-calendar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-calendar@latest"],
      "env": {
        "GOOGLE_CALENDAR_CLIENT_ID": "${input:calendar_client_id}",
        "GOOGLE_CALENDAR_CLIENT_SECRET": "${input:calendar_client_secret}",
        "GOOGLE_CALENDAR_REFRESH_TOKEN": "${input:calendar_refresh_token}"
      }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "calendar_client_id", "description": "Google OAuth client ID" },
    { "type": "promptString", "id": "calendar_client_secret", "description": "Google OAuth client secret", "password": true },
    { "type": "promptString", "id": "calendar_refresh_token", "description": "Google OAuth refresh token", "password": true }
  ]
}

Qué puedes pedirle que haga

Ver tu agenda

• ¿Qué reuniones tengo esta semana? Incluye las recurrentes.
• Muestra el 1:1 de mañana con sus invitados, enlace de Meet y recordatorios.
• Enumera cada ocurrencia de la sincronización de equipo en marzo.

Planificar y cambiar reuniones

• Crea una revisión de 45 minutos el jueves con dos invitados y un enlace de Google Meet.
• Reprograma la retrospectiva una hora más tarde y actualiza la lista de invitados, pero no envíes correos todavía.
• Mueve el evento de planificación al calendario del equipo.
• Cancela la ocurrencia del viernes de la reunión diaria, dejando el resto de la serie intacta.

Proteger tu tiempo

• ¿Cuándo están libres Anna, Boris y yo durante una hora la próxima semana?
• Bloquea Fuera de Oficina para mis vacaciones y rechaza automáticamente nuevas invitaciones.
• Crea dos horas de Tiempo de Enfoque mañana por la mañana y silencia Google Chat.

Cómo cambia un evento

1. calendar_id: "primary" es tu calendario principal; otros calendarios provienen de list_calendars, y las escrituras requieren acceso de escritor.
2. Una serie recurrente y una ocurrencia individual tienen ids diferentes: el id de la serie cambia o cancela cada ocurrencia; un id de instancia (de list_event_instances) exactamente una.
3. update_event cambia solo los campos que proporcionas, pero un objeto anidado reemplaza a su predecesor por completo: una nueva lista attendees reemplaza toda la lista de invitados.
4. Ninguna escritura envía correos a nadie a menos que send_updates lo indique: el valor predeterminado de la API de Calendar es el silencio.

Los bloques de Fuera de Oficina y Tiempo de Enfoque existen solo en el calendario principal de una cuenta de Google Workspace; Gmail de consumidor y calendarios secundarios los rechazan. Crear un evento no verifica conflictos: pide una verificación de disponibilidad primero. Los eventos de día completo terminan en una fecha exclusiva: un evento hasta el viernes termina en la fecha del sábado.

Qué puede cambiar

El cliente de IA controla los mensajes de confirmación. El servidor marca las herramientas de lectura, escritura y destructivas para que el cliente pueda distinguir una inspección de un cambio en vivo.

Obtener acceso

El acceso a tus propios calendarios requiere OAuth 2.0; una clave de API no es suficiente. Hay dos formas de conectarse, y la primera no necesita ningún archivo de configuración.

Iniciar sesión desde el chat

Inicia el servidor sin credenciales y pide al asistente que se conecte. Te guía con seis herramientas integradas:

El inicio de sesión surte efecto de inmediato: la siguiente llamada a una herramienta funciona sin reiniciar el cliente de IA. El token se almacena en ~/.config/mcp-google-calendar/credentials.json (en Windows, en %APPDATA%), legible solo por tu cuenta, y nunca sale de tu máquina.

O configurar variables de entorno

La ruta clásica, y la indicada para CI e instalaciones sin interfaz gráfica:

1. Crea o selecciona un proyecto de Google Cloud y habilita Google Calendar API.

2. Configura la pantalla de consentimiento OAuth y crea un cliente OAuth de Aplicación de escritorio.

3. Autoriza la cuenta de Google cuyos calendarios quieres gestionar. El OAuth 2.0 Playground puede obtener el token de actualización cuando Usar tus propias credenciales OAuth está habilitado.

4. Solicita ambos ámbitos:

   https://www.googleapis.com/auth/calendar.events
   https://www.googleapis.com/auth/calendar.readonly
   

   El ámbito amplio https://www.googleapis.com/auth/calendar solo se necesita para llamadas raw_request que gestionan calendarios o reglas de uso compartido.

Las variables de entorno siempre tienen prioridad sobre un inicio de sesión realizado en el chat, por lo que una instalación configurada existente sigue comportándose exactamente como antes.

Los tokens de actualización OAuth en modo de prueba pueden expirar después de siete días. Publica la aplicación OAuth o usa una aplicación Interna en un dominio de Workspace cuando necesites acceso de larga duración. Trata el secreto del cliente y el token de actualización como contraseñas.

Configuración

* Proporciona el trío OAuth o un token de acceso. Sin credenciales, el servidor aún se inicia y completa el protocolo de enlace MCP; la primera llamada a una herramienta entonces nombra las variables exactas a configurar.

Datos, límites y trabajo en segundo plano

• Las solicitudes van a Google Calendar. El servidor local actualiza los tokens OAuth de Google y llama a la API de Calendar. Su telemetría anónima contiene un ID de instalación, versión del paquete, cliente de IA y versiones de plataforma, y nombres de herramientas: nunca tokens OAuth, datos de calendario, argumentos de herramientas o indicaciones. Configura ASKADS_TELEMETRY=0 para optar por no participar.
• Google aplica cuotas por proyecto. En 429, el servidor reintenta con retroceso; las lecturas también reintentan después de errores de red y 5xx, mientras que las escrituras no se reproducen después de un fallo incierto: un evento duplicado podría reenviar correos a todos los invitados.
• No hay sondeo en segundo plano. El servidor solo se ejecuta cuando se le llama. list_events admite verificaciones incrementales mediante updated_min; si tu aplicación de IA admite tareas programadas, puede verificar tu calendario periódicamente.

Documentación técnica

• Catálogo de capacidades MCP: páginas orientadas a tareas para cada herramienta.
• Todas las herramientas y entradas
• Documentación de desarrollo
• Documentación de publicación
• Referencia de la API de Google Calendar

Soporte

¿Encontraste un error o necesitas un escenario? Crea un problema o escribe en Telegram.

¡Llegaste al final!