Google Calendar MCP Server

# 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](https://console.cloud.google.com/) 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](https://developers.google.com/oauthplayground/) 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: ```bash cp env.example .env ``` Edita `.env` con tus valores: ```env 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 ```bash # 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](RAILWAY_DEPLOY.md) 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`: ```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: ```json { "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