Servidor MCP de autenticación automática de Google Calendar

Un servidor de Protocolo de Contexto de Modelo (MCP) para la integración de Google Calendar en Claude Desktop con compatibilidad con autenticación automática. Este servidor permite que los asistentes de IA administren Google Calendar mediante interacciones de lenguaje natural.

Características

Crea eventos de calendario con título, descripción, ubicación y asistentes.
Actualizar los eventos del calendario existentes
Eliminar eventos del calendario
Recuperar detalles del evento
Enumerar eventos dentro de un rango de tiempo específico
Buscar eventos por palabra clave
Listar todos los calendarios disponibles
Admite entrada de fecha y hora en lenguaje natural (por ejemplo, "mañana a las 2 p. m.", "el próximo lunes")
Integración completa con la API de Google Calendar
Flujo de autenticación OAuth2 simple con inicio automático del navegador
Compatibilidad con credenciales de aplicaciones web y de escritorio
Almacenamiento global de credenciales para mayor comodidad

Instalación y autenticación

Instalación manual

Crea un proyecto de Google Cloud y obtén las credenciales:a. Crear un proyecto de Google Cloud:
- Ir a la consola de Google Cloud
- Crea un nuevo proyecto o selecciona uno existente
- Habilite la API de Google Calendar para su proyecto
b. Crear credenciales OAuth 2.0:
- Vaya a "API y servicios" > "Credenciales".
- Haga clic en "Crear credenciales" > "ID de cliente OAuth".
- Elija "Aplicación de escritorio" o "Aplicación web" como tipo de aplicación
- Dale un nombre y haz clic en "Crear"
- Para la aplicación web, agregue http://localhost:3000/oauth2callback a las URI de redireccionamiento autorizadas
- Descargue el archivo JSON de las claves OAuth de su cliente
- Cambie el nombre del archivo de clave a gcp-oauth.keys.json
Ejecutar autenticación:Puedes autenticarte de dos maneras:a. Autenticación global (recomendada):
# First time: Place gcp-oauth.keys.json in your home directory's .calendar-mcp folder mkdir -p ~/.calendar-mcp mv gcp-oauth.keys.json ~/.calendar-mcp/ # Run authentication from anywhere npx @nchufa/calendar auth
b. Autenticación local:
# Place gcp-oauth.keys.json in your current directory # The file will be automatically copied to global config npx @nchufa/calendar auth
El proceso de autenticación:
- Busque gcp-oauth.keys.json en el directorio actual o ~/.calendar-mcp/
- Si se encuentra en el directorio actual, cópielo a ~/.calendar-mcp/
- Abra su navegador predeterminado para la autenticación de Google
- Guardar las credenciales como ~/.calendar-mcp/credentials.json
Nota :
- Después de una autenticación exitosa, las credenciales se almacenan globalmente en ~/.calendar-mcp/ y se pueden usar desde cualquier directorio.
- Se admiten credenciales tanto de aplicaciones de escritorio como de aplicaciones web
- Para las credenciales de la aplicación web, asegúrese de agregar http://localhost:3000/oauth2callback a sus URI de redireccionamiento autorizados
Configurar en Claude Desktop:

Agregue lo siguiente a su archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "calendar": {
      "command": "npx",
      "args": [
        "@nchufa/calendar"
      ]
    }
  }
}

Herramientas disponibles

El servidor proporciona las siguientes herramientas que se pueden utilizar a través de Claude Desktop:

1. Crear evento ( `create_event` )

Crea un nuevo evento de calendario.

{
  "summary": "Team Meeting",
  "description": "Weekly team sync to discuss project progress",
  "location": "Conference Room A",
  "start": "2025-04-01T14:00:00",
  "end": "2025-04-01T15:00:00",
  "attendees": ["colleague@example.com", "manager@example.com"],
  "reminders": {
    "useDefault": false,
    "overrides": [
      {
        "method": "email",
        "minutes": 30
      },
      {
        "method": "popup",
        "minutes": 10
      }
    ]
  }
}

También se admite fecha y hora en lenguaje natural:

{
  "summary": "Coffee with John",
  "location": "Starbucks Downtown",
  "start": "tomorrow at 2:30pm",
  "end": "tomorrow at 3:30pm"
}

2. Obtener evento ( `get_event` )

Recupera detalles de un evento de calendario específico.

{
  "eventId": "abc123xyz456",
  "calendarId": "primary"
}

3. Evento de actualización ( `update_event` )

Actualiza un evento de calendario existente.

{
  "eventId": "abc123xyz456",
  "summary": "Updated Meeting Title",
  "location": "New Location",
  "start": "2025-04-01T15:00:00",
  "end": "2025-04-01T16:00:00"
}

4. Eliminar evento ( `delete_event` )

Elimina un evento del calendario.

{
  "eventId": "abc123xyz456",
  "calendarId": "primary"
}

5. Lista de eventos ( `list_events` )

Enumera los eventos del calendario dentro de un rango de tiempo específico.

{
  "calendarId": "primary",
  "timeMin": "2025-04-01T00:00:00",
  "timeMax": "2025-04-07T23:59:59",
  "maxResults": 10,
  "orderBy": "startTime"
}

6. Buscar eventos ( `search_events` )

Busca eventos que coincidan con una consulta.

{
  "query": "meeting",
  "calendarId": "primary",
  "timeMin": "2025-04-01T00:00:00",
  "maxResults": 5
}

7. Lista de calendarios ( `list_calendars` )

Enumera todos los calendarios disponibles.

{}

Compatibilidad con fecha y hora en lenguaje natural

El servidor admite varios formatos de lenguaje natural para fechas y horas:

Fechas específicas: "2025-04-01T14:00:00" (formato ISO)
Referencias simples: «hoy», «mañana», «ahora»
Tiempos relativos: "2 horas después", "3 días después"
Referencias diarias: "el próximo lunes", "el próximo martes"
Formatos combinados: "mañana a las 14h", "lunes a las 15:30h"

Esto facilita la creación y actualización de eventos utilizando instrucciones en lenguaje natural.

Notas de seguridad

Las credenciales de OAuth se almacenan de forma segura en su entorno local ( ~/.calendar-mcp/ )
El servidor utiliza acceso sin conexión para mantener una autenticación persistente
Nunca comparta ni comprometa sus credenciales con el control de versiones
Revise y revoque periódicamente el acceso no utilizado en la configuración de su cuenta de Google

Solución de problemas

Claves OAuth no encontradas
- Asegúrese de que gcp-oauth.keys.json esté en su directorio actual o en ~/.calendar-mcp/
- Comprobar permisos de archivos
Formato de credenciales no válidas
- Asegúrese de que su archivo de claves OAuth contenga credenciales web o installed
- Para aplicaciones web, verifique que la URI de redireccionamiento esté configurada correctamente
Puerto ya en uso
- Si el puerto 3000 ya está en uso, libérelo antes de ejecutar la autenticación
- Puedes encontrar y detener el proceso usando ese puerto

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Licencia

Instituto Tecnológico de Massachusetts (MIT)

Expresiones de gratitud

Un agradecimiento especial a GongRzhe y su proyecto Calendar-Autoauth-MCP-Server que sirvió como base para esta implementación.

Apoyo

Si encuentra algún problema o tiene preguntas, envíe un problema en el repositorio de GitHub.