Google Calendar

Google Calendar MCP Server

Un servidor de Model Context Protocol (MCP) que se integra con Google Calendar, construido con TypeScript.

Características

• Integración perfecta con Google Calendar mediante autenticación OAuth 2.0
• Almacenamiento persistente de tokens para autenticación automática
• Lista y gestiona calendarios con operaciones completas de eventos
• Crea, lee, actualiza y elimina eventos del calendario
• Obtén eventos del calendario entre fechas especificadas
• Opción de transporte Server-Sent Events (SSE) para actualizaciones en tiempo real
• Integración sencilla con Claude y otros asistentes de IA compatibles con MCP

Instalación

npm install -g mcp-google-calendar

O ejecuta directamente con:

npx -y mcp-google-calendar

Requisitos previos

1. Node.js (v16 o superior)
2. Cuenta de Google Cloud Platform
3. API de Google Calendar habilitada
4. Credenciales OAuth 2.0

Configuración

1. Configuración de Google Cloud

1. Ve a Google Cloud Console
2. Crea un nuevo proyecto o selecciona uno existente
3. Habilita la API de Google Calendar:
   • Navega a "APIs & Services" > "Library"
   • Busca "Google Calendar API"
   • Haz clic en "Enable"
4. Configura la pantalla de consentimiento de OAuth:
   • Ve a "APIs & Services" > "OAuth consent screen"
   • Elige el tipo de usuario "External" (o "Internal" para Google Workspace)
   • Completa la información requerida:
     • Nombre de la aplicación: mcp-calendar
     • Correo de soporte al usuario: (tu correo)
     • Información de contacto del desarrollador: (tu correo)
   • Añade ámbitos (scopes):
     • Haz clic en "Add or Remove Scopes"
     • Busca y selecciona "https://www.googleapis.com/auth/calendar.events"
     • Añade tu correo como usuario de prueba
   • Completa la configuración
5. Crea credenciales de OAuth:
   • Ve a "Credentials"
   • Haz clic en "Create Credentials" > "OAuth Client ID"
   • Elige "Desktop app" como tipo de aplicación
   • Asígnale un nombre (por ejemplo, "MCP Calendar Desktop Client")
   • Descarga el archivo JSON y guárdalo como credentials.json en el directorio de tu proyecto

2. Configuración del entorno

Crea un archivo .env en la raíz de tu proyecto:

# Server configuration
PORT=3420

# Google Calendar API configuration
CREDENTIALS_PATH=./credentials.json

Uso

Iniciar el servidor

Inicia con WebSockets estándar:

npx -y mcp-google-calendar

Inicia con Server-Sent Events (SSE):

npx -y mcp-google-calendar --sse

Con Claude Desktop

Añade esto a tu claude_desktop_config.json:

{
   "mcpServers": {
      "mcp-google-calendar": {
         "command": "npx",
         "args": ["-y", "mcp-google-calendar"],
         "env": {
            "CREDENTIALS_PATH": "/path/to/your/credentials.json"
         }
      }
   }
}

Proceso de autenticación

La primera vez que ejecutes el servidor:

1. Se abrirá una ventana del navegador automáticamente
2. Inicia sesión con tu cuenta de Google
3. Concede los permisos de calendario solicitados
4. El token de autenticación se guarda en token.json

En lanzamientos posteriores:

• El servidor utiliza el token guardado automáticamente
• No se requiere interacción con el navegador a menos que el token expire

Herramientas disponibles

Herramienta	Descripción
list_calendars	Obtén todos los calendarios disponibles
list_calendar_events	Recupera eventos entre fechas especificadas
create_calendar_event	Añade un nuevo evento a tu calendario
get_calendar_event	Obtén detalles de un evento específico
edit_calendar_event	Modifica un evento existente del calendario
delete_calendar_event	Elimina un evento de tu calendario

Desarrollo

Clona y configura el proyecto:

git clone https://github.com/am2rican5/mcp-google-calendar.git
cd mcp-google-calendar
npm install

Compila el proyecto:

npm run build

Ejecuta en modo de desarrollo:

npm start

Consideraciones de seguridad

⚠️ Advertencia de seguridad importante ⚠️

• credentials.json y token.json contienen información de autenticación sensible
• Nunca subas estos archivos al control de versiones ni los compartas públicamente
• Cada usuario debe crear sus propias credenciales de OAuth
• Si sospechas que tus credenciales están comprometidas, revócalas inmediatamente en Google Cloud Console
• El token concede acceso a los datos de tu Google Calendar

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

1. Haz un fork del repositorio
2. Crea tu rama de características (git checkout -b feature/amazing-feature)
3. Haz commit de tus cambios (git commit -m 'Add some amazing feature')
4. Sube los cambios a la rama (git push origin feature/amazing-feature)
5. Abre un Pull Request