MCP Google Calendar Plus

Un servidor para la gestión completa de Google Calendar, incluyendo la creación, actualización y eliminación de eventos. Requiere autenticación mediante Google OAuth2.

GitHub

Documentación

MCP Google Workspace

El ÚNICO servidor MCP completo para Google Workspace que permite a Claude, Cursor, Windsurf y otros sistemas de IA gestionar completamente Google Calendar, Contacts Y Gmail - ¡leer, crear, actualizar, eliminar y organizar en los tres servicios!

Integración completa de Google Workspace para Claude Desktop y otros agentes de IA mediante el Protocolo de Contexto de Modelos (MCP). Este servidor proporciona capacidades integrales de gestión para Calendar, Contacts y Gmail con autenticación OAuth2.

¿Por qué este servidor MCP?

Otros servidores MCP de calendario solo ofrecen acceso de solo lectura. Este es el único servidor MCP que permite a sistemas de IA como Claude, Cursor y Windsurf:

Gestión de Calendario

  • ✅ Crear nuevos eventos de calendario
  • ✅ Actualizar eventos existentes (incluidos eventos recurrentes)
  • ✅ Eliminar eventos
  • ✅ Gestionar múltiples calendarios
  • ✅ Comprobar disponibilidad en varios calendarios

Gestión de Contactos

  • ✅ Listar y buscar contactos
  • ✅ Crear nuevos contactos con todos los detalles
  • ✅ Actualizar contactos existentes
  • ✅ Eliminar contactos
  • ✅ Gestionar detalles de contacto (correos electrónicos, teléfonos, direcciones, organizaciones)

Gestión de Gmail (¡NUEVO!)

  • ✅ Buscar y listar correos electrónicos con potentes consultas
  • ✅ Leer el contenido completo de los correos con archivos adjuntos
  • ✅ Enviar nuevos correos y respuestas
  • ✅ Organizar con etiquetas y carpetas
  • ✅ Actualizar el estado del correo (leído/no leído, destacado, importante)
  • ✅ Crear y gestionar borradores
  • ✅ Operaciones por lotes para la gestión masiva de correos

Características

Funciones de Calendario

  • Soporte multi-calendario: Lista eventos de múltiples calendarios simultáneamente
  • Gestión de eventos: Crear, actualizar (incluidas notificaciones), eliminar y buscar eventos de calendario
  • Eventos recurrentes: Ámbitos de modificación avanzados para eventos recurrentes (instancia única, todas las instancias o solo instancias futuras)
  • Gestión de calendarios: Listar calendarios y sus propiedades
  • Consultas de disponibilidad: Comprobar disponibilidad en varios calendarios

Funciones de Contactos

  • Búsqueda de contactos: Buscar contactos por nombre, correo electrónico u otros criterios
  • Detalles completos de contacto: Gestionar nombres, correos electrónicos, números de teléfono, direcciones, organizaciones y notas
  • Operaciones por lotes: Listar contactos con soporte de paginación
  • Selección de campos: Elegir qué campos de contacto recuperar para respuestas optimizadas

Funciones de Gmail (¡NUEVO!)

  • Búsqueda avanzada: Utiliza los potentes operadores de búsqueda de Gmail
  • Gestión de correos: Leer, enviar, responder, reenviar y eliminar correos electrónicos
  • Organización con etiquetas: Crear y gestionar etiquetas/carpetas
  • Gestión de borradores: Crear, actualizar y enviar borradores
  • Operaciones por lotes: Actualizar múltiples correos a la vez
  • Soporte de hilos: Gestionar conversaciones de correo
  • Información de adjuntos: Ver detalles de archivos adjuntos (nombres, tamaños, tipos)

Autenticación

  • Autenticación OAuth2: Autenticación segura con renovación automática de tokens
  • Permisos unificados: Un único flujo de autenticación para el acceso a Calendar, Contacts y Gmail

Instalación

Mediante npx (Recomendado)

npx mcp-google

Mediante npm

npm install -g mcp-google

Configuración

1. Crear credenciales OAuth de Google

  1. Ve a Google Cloud Console
  2. Crea un nuevo proyecto o selecciona uno existente
  3. Habilita estas API:
  4. Configura la pantalla de consentimiento OAuth:
    • Ve a "API y Servicios" > "Pantalla de consentimiento OAuth"
    • Elige el tipo de usuario "Externo"
    • Completa los campos obligatorios (nombre de la aplicación, correo de soporte, etc.)
    • Añade tu correo electrónico como usuario de prueba (necesario mientras esté en modo de prueba)
  5. Crea las credenciales OAuth 2.0:
    • Ve a "API y Servicios" > "Credenciales"
    • Haz clic en "Crear credenciales" > "ID de cliente OAuth"
    • Elige "Aplicación de escritorio" como tipo de aplicación
    • Pon nombre a tu cliente OAuth (por ejemplo, "Cliente MCP de Calendar")
    • Descarga el archivo JSON de credenciales

2. Configurar Claude Desktop

Añade esto a tu archivo de configuración de Claude Desktop:

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

Opción A: Variables de entorno directas (la más sencilla: ¡no se necesita archivo JSON!)

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "mcp-google"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Opción B: Usar el archivo de credenciales de Google descargado

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "mcp-google"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/downloaded/credentials.json"
      }
    }
  }
}

Simplemente usa la ruta del archivo donde guardaste el archivo JSON descargado de Google Cloud Console.

3. Autenticarse

  1. Reinicia Claude Desktop
  2. El servidor MCP abrirá una ventana del navegador para la autenticación
  3. Inicia sesión con tu cuenta de Google y concede permisos de Calendar, Contacts Y Gmail
  4. Los tokens se guardarán de forma segura para uso futuro

Nota: Si estás actualizando desde una versión anterior, deberás volver a autenticarte para conceder los nuevos permisos de Gmail.

Variables de Entorno

  • GOOGLE_OAUTH_CREDENTIALS: Ruta al archivo JSON de credenciales OAuth
  • GOOGLE_CALENDAR_MCP_TOKEN_PATH: Ruta personalizada para el almacenamiento de tokens (opcional)
  • NODE_ENV: Establecer en "production" para uso en producción

Herramientas Disponibles

Herramientas de Calendario

list-calendars

Lista todos los calendarios accesibles con sus propiedades.

list-events

Lista eventos de uno o más calendarios con opciones de filtrado.

create-event

Crea un nuevo evento de calendario con soporte para:

  • Eventos únicos o recurrentes
  • Asistentes y notificaciones
  • Colores personalizados
  • Zonas horarias

update-event

Actualiza eventos existentes, incluyendo:

  • Modificación de instancias individuales de eventos recurrentes
  • Cambio de detalles del evento
  • Gestión de asistentes

delete-event

Elimina eventos de calendarios.

search-events

Busca eventos en varios calendarios mediante consultas de texto.

get-freebusy

Consulta información de disponibilidad en múltiples calendarios.

list-colors

Lista los colores disponibles para eventos de calendario.

Herramientas de Contactos

list-contacts

Lista y busca contactos con soporte de paginación.

get-contact

Obtiene información detallada sobre un contacto específico.

create-contact

Crea nuevos contactos con:

  • Nombres y apodos
  • Múltiples direcciones de correo electrónico
  • Números de teléfono
  • Direcciones físicas
  • Organizaciones y cargos
  • Notas y biografías

update-contact

Actualiza información de contactos existentes con actualizaciones específicas por campo.

delete-contact

Elimina contactos de Google Contacts.

Herramientas de Gmail (¡NUEVO!)

list-emails

Busca y lista correos electrónicos con potentes consultas de Gmail.

get-email

Lee el contenido completo del correo, incluido el cuerpo y los archivos adjuntos.

send-email

Envía nuevos correos electrónicos o respuestas con soporte de HTML.

update-email

Modifica propiedades del correo (etiquetas, estado de lectura, destacado, archivado).

delete-email

Mueve correos a la papelera o los elimina permanentemente.

create-draft

Crea borradores de correo para editar más tarde.

update-draft

Edita borradores de correo existentes.

send-draft

Envía un borrador guardado.

list-labels

Lista todas las etiquetas/carpetas de Gmail.

create-label

Crea nuevas etiquetas para organizar correos.

update-label

Modifica propiedades y colores de las etiquetas.

delete-label

Elimina etiquetas de Gmail.

batch-update-emails

Realiza operaciones masivas en múltiples correos.

Ejemplos de Uso

Ejemplos de Calendario

Consultar disponibilidad

What times am I free tomorrow between 9am and 5pm?

Crear un evento

Create a meeting called "Team Standup" tomorrow at 10am for 30 minutes

Buscar eventos

Find all events this week that mention "project review"

Actualizar eventos recurrentes

Change all future instances of my weekly team meeting to 2pm

Ejemplos de Contactos

Listar contactos

Show me all my contacts with email addresses

Crear un contacto

Create a contact for John Doe, email: john@example.com, phone: 555-1234

Buscar contactos

Find contacts who work at Google

Actualizar contacto

Update Jane Smith's phone number to 555-5678

Ejemplos de Gmail

Buscar correos

Show me all unread emails from this week

Enviar correo

Send an email to john@example.com with subject "Meeting Tomorrow" and body "Let's meet at 2pm"

Organizar la bandeja de entrada

Mark all newsletters as read and archive them

Gestionar etiquetas

Create a label called "Important Projects" and apply it to all emails from my manager

Operaciones por lotes

Move all emails older than 30 days to trash

Solución de Problemas

Problemas de Autenticación

  • Asegúrate de que la URI de redirección coincida exactamente: http://localhost:3000/oauth2callback
  • Comprueba que tanto la API de Calendar como la de People estén habilitadas en Google Cloud Console
  • Verifica que las credenciales OAuth sean de tipo "Aplicación de escritorio"
  • Si actualizas desde una versión solo de calendario, vuelve a ejecutar la autenticación para conceder permisos de contactos

Caducidad del Token

  • Los tokens se renuevan automáticamente
  • Si los problemas persisten, elimina el archivo de token y vuelve a autenticarte

Errores de Permisos

  • Asegúrate de haber concedido todos los permisos solicitados de Calendar, Contacts y Gmail
  • Comprueba que la cuenta de Google tenga acceso a los recursos a los que intentas acceder
  • Asegúrate de que todas las API necesarias estén habilitadas en tu proyecto de Google Cloud:
    • Google Calendar API
    • Google People API
    • Gmail API

Seguridad

  • Los tokens OAuth se almacenan con permisos restringidos (0600)
  • Los secretos de cliente nunca deben enviarse al control de versiones
  • Usa variables de entorno para la configuración sensible

Desarrollo

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

Equipo

Desarrollado por Boris Djordjevic y el equipo de 199 Longevity.

Construido sobre el google-calendar-mcp original de nspady.

Licencia

MIT

Contribuciones

¡Las contribuciones son bienvenidas! Abre un issue o envía un pull request en GitHub.

Historial de Cambios

v1.1.3

  • Corregida la validación de zona horaria para admitir milisegundos en marcas de tiempo ISO
  • Ahora es compatible con el formato Date.toISOString() de JavaScript (por ejemplo, 2024-01-01T00:00:00.000Z)
  • Mejorada la expresión regular de validación de fecha y hora para manejar ambos formatos, con y sin milisegundos

v1.1.2

  • Mejorado el flujo de autenticación con una página de destino clara e informativa
  • Los usuarios ahora ven exactamente qué permisos tendrá Claude antes de conectarse
  • Interfaz profesional que identifica claramente esto como autenticación de Google Calendar
  • Añadida nota de seguridad de que las credenciales nunca se almacenan

v1.1.1

  • Documentación mejorada para destacar las capacidades únicas de gestión completa del calendario
  • Añadida la sección "¿Por qué este servidor MCP?" que enfatiza las funciones de crear/actualizar/eliminar
  • Actualizada la descripción del paquete y las palabras clave para una mejor visibilidad

v1.1.0

  • Configuración simplificada: Añadido soporte para variables de entorno directas (¡no se necesita archivo JSON!)
  • Los usuarios ahora pueden usar GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET directamente en la configuración de Claude
  • README actualizado con instrucciones más claras para la configuración OAuth de aplicación de escritorio
  • Eliminados los pasos innecesarios de configuración de la URI de redirección

v1.0.1

  • Añadida lógica de reintento automático para errores de red
  • Mejorado el manejo de errores para problemas de conexión interrumpida
  • Recuperación silenciosa cuando los eventos se crean a pesar de errores de conexión

v1.0.0

  • Versión inicial con autenticación OAuth2 mejorada
  • Herramientas integrales de gestión de calendario
  • Soporte multi-calendario
  • Consultas de disponibilidad