mcp-gcal

Servidor MCP (Model Context Protocol) para interactuar con Google Calendar. Permite a modelos de lenguaje crear, obtener, listar, actualizar y eliminar eventos de calendario.

🚀 Características

• Crear eventos: Crea eventos con título, descripción, ubicación, asistentes y más.
• Obtener eventos: Recupera información detallada de un evento por su ID.
• Listar eventos: Lista eventos en un rango de fechas con filtros de búsqueda.
• Actualizar eventos: Modifica parcialmente eventos existentes.
• Eliminar eventos: Elimina eventos del calendario.

📋 Requisitos

• Node.js 20 o superior
• Una cuenta de Google con acceso a Google Calendar
• Credenciales OAuth2 de Google Cloud Console

⚙️ Configuración

1. Crear proyecto en Google Cloud Console

1. Ve a Google Cloud Console
2. Crea un nuevo proyecto o selecciona uno existente
3. Ve a APIs & Services > Library
4. Busca y habilita Google Calendar API

2. Configurar credenciales OAuth2

1. Ve a APIs & Services > Credentials
2. Click en Create Credentials > OAuth client ID
3. Selecciona Desktop app o Web application
4. Configura el redirect URI: http://localhost:3000/oauth2callback
5. Guarda el Client ID y Client Secret

3. Obtener el Refresh Token

Para obtener el refresh_token, puedes usar el OAuth 2.0 Playground de Google:

1. Ve a https://developers.google.com/oauthplayground/
2. Click en el engranaje (⚙️) arriba a la derecha
3. Marca "Use your own OAuth credentials"
4. Introduce tu Client ID y Client Secret
5. En la columna izquierda, busca Google Calendar API v3
6. Selecciona el scope: https://www.googleapis.com/auth/calendar
7. Click en Authorize APIs y autoriza tu cuenta
8. Click en Exchange authorization code for tokens
9. Copia el refresh_token del resultado

4. Configurar variables de entorno

Copia el archivo de ejemplo y rellena tus credenciales:

cp env.example .env

Edita .env con tus valores:

GOOGLE_CLIENT_ID=123456789-abc123.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxx
GOOGLE_REFRESH_TOKEN=1//0xxxxxxxxxxxxxxxxxxxxxx
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback
GOOGLE_CALENDAR_ID=primary
LOG_LEVEL=info

🔧 Instalación y Ejecución

# Instalar dependencias
npm install

# Compilar TypeScript
npm run build

# Ejecutar el servidor
npm start

🚂 Despliegue en Railway

Este proyecto puede desplegarse como API REST en Railway. Consulta la guía completa de despliegue para instrucciones detalladas.

Resumen rápido:

1. Conecta tu repositorio a Railway
2. Configura las variables de entorno (Google OAuth2 o Service Account)
3. Railway construirá y desplegará automáticamente
4. Accede a tu API en la URL proporcionada por Railway

Endpoints disponibles:

• GET /health - Health check
• POST /api/events - Crear evento
• GET /api/events/:eventId - Obtener evento
• GET /api/events - Listar eventos
• PUT /api/events/:eventId - Actualizar evento
• DELETE /api/events/:eventId - Eliminar evento

🔌 Integración con Cursor/Claude

Añade el servidor a tu configuración de MCP. En Cursor, añade al archivo ~/.cursor/mcp.json:

{
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": ["ruta/a/mcp-gcal/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "tu-client-id",
        "GOOGLE_CLIENT_SECRET": "tu-client-secret",
        "GOOGLE_REFRESH_TOKEN": "tu-refresh-token",
        "GOOGLE_REDIRECT_URI": "http://localhost:3000/oauth2callback",
        "GOOGLE_CALENDAR_ID": "primary"
      }
    }
  }
}

🛠️ Tools Disponibles

create_event

Crea un nuevo evento en el calendario.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
summary	string	✅	Título del evento
start	string	✅	Fecha/hora inicio (ISO 8601)
end	string	✅	Fecha/hora fin (ISO 8601)
description	string	❌	Descripción del evento
location	string	❌	Ubicación
calendarId	string	❌	ID del calendario (default: primary)
timeZone	string	❌	Zona horaria (default: Europe/Madrid)
attendees	string[]	❌	Emails de asistentes

get_event

Obtiene un evento por su ID.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
eventId	string	✅	ID del evento
calendarId	string	❌	ID del calendario

list_events

Lista eventos en un rango de fechas.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
timeMin	string	✅	Fecha/hora mínima (ISO 8601)
timeMax	string	✅	Fecha/hora máxima (ISO 8601)
maxResults	number	❌	Máximo de resultados (default: 50)
calendarId	string	❌	ID del calendario
q	string	❌	Texto de búsqueda

update_event

Actualiza parcialmente un evento existente.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
eventId	string	✅	ID del evento
calendarId	string	❌	ID del calendario
summary	string	❌	Nuevo título
description	string	❌	Nueva descripción
location	string	❌	Nueva ubicación
start	string	❌	Nueva fecha/hora inicio
end	string	❌	Nueva fecha/hora fin
timeZone	string	❌	Nueva zona horaria
attendees	string[]	❌	Nuevos asistentes

delete_event

Elimina un evento del calendario.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
eventId	string	✅	ID del evento
calendarId	string	❌	ID del calendario

💬 Ejemplos de Uso

Estos son ejemplos de prompts que puedes usar con un modelo de lenguaje conectado a este MCP:

Crear un evento

"Crea un evento de 30 minutos mañana a las 10:00 llamado 'Preparar presentación' en mi calendario principal."

Listar eventos

"Lista los eventos de la próxima semana que contengan la palabra 'reunión'."

Actualizar un evento

"Actualiza el evento con id 'abc123xyz' para moverlo a las 11:00."

Eliminar un evento

"Elimina el evento con id 'abc123xyz'."

📦 Estructura del Proyecto

mcp-gcal/
├── src/
│   ├── index.ts          # Punto de entrada del MCP
│   ├── gcalClient.ts     # Cliente OAuth2 de Google Calendar
│   ├── tools/
│   │   ├── createEvent.ts
│   │   ├── getEvent.ts
│   │   ├── listEvents.ts
│   │   ├── updateEvent.ts
│   │   ├── deleteEvent.ts
│   │   └── index.ts
│   ├── types/
│   │   └── index.ts      # Tipos TypeScript compartidos
│   └── utils/
│       ├── errors.ts     # Manejo de errores
│       └── logger.ts     # Logging
├── dist/                 # Código compilado
├── manifest.json         # Definición del MCP
├── package.json
├── tsconfig.json
├── env.example
└── README.md

🐛 Manejo de Errores

Los errores se devuelven en formato JSON estructurado:

{
  "type": "validation_error",
  "message": "El campo 'summary' es requerido",
  "details": {
    "field": "summary"
  }
}

Tipos de error:

• auth_error: Problemas de autenticación con Google
• validation_error: Parámetros inválidos o faltantes
• google_api_error: Errores de la API de Google Calendar
• not_found_error: Recurso no encontrado
• unknown_error: Errores no categorizados

📝 Licencia

MIT