UNC LibCal MCP

Servidor MCP para reservar espacios de estudio de UNC Davis Library desde Claude, Cursor, Codex o cualquier cliente MCP, con integración opcional de Apple Calendar.

Hecho para estudiantes, profesorado y personal de UNC con un Onyen válido. No está afiliado ni respaldado por UNC Libraries.

Qué hace

Pídele a tu agente:

Reserva un cubículo de Davis mañana a las 2 pm

El servidor hará lo siguiente:

1. Comprobará la disponibilidad en LibCal (API pública — no se necesita inicio de sesión)

2. Sugerirá opciones ordenadas (libcal_suggest) o reservará un espacio que confirmes (libcal_book)

3. Completará la reserva en tu sesión del navegador (Playwright + inicio de sesión guardado de Onyen)

4. Añadirá opcionalmente el evento a Apple Calendar (solo macOS)

Related MCP server: @aiwerk/mcp-server-cal

Requisitos

• Node.js 20+

• UNC Onyen (para reservar; las comprobaciones de disponibilidad funcionan sin iniciar sesión)

• macOS para la sincronización con Apple Calendar (opcional)

• Chromium (se instala automáticamente mediante Playwright)

Inicio rápido

1. Clona e instala

git clone https://github.com/Thespaceblade/unc-libcal-mcp.git
cd unc-libcal-mcp
npm install
npx playwright install chromium
npm run build
npm test

2. Inicia sesión en LibCal

npm run login

Se abre un navegador → inicia sesión con tu Onyen (+ Duo si se solicita) → cuando se cargue la página de Davis LibCal, pulsa Enter en la terminal.

Tu sesión se guarda en ~/.unc-libcal/storage-state.json (nunca hagas commit de este archivo).

3. Configura (opcional)

En la primera ejecución, se crea ~/.unc-libcal/config.json con valores predeterminados:

{
  "defaultCategory": "davis-cubes",
  "calendarName": "Calendar",
  "preferSameDay": true,
  "minLeadMinutes": 30,
  "searchHorizonDays": 7,
  "bookingPurpose": "Study session"
}

Pide al agente que ejecute libcal_list_calendars y luego establece calendarName en tu Apple Calendar preferido. Concede el permiso de Automatización cuando macOS lo solicite (Terminal o Cursor → Calendar).

4. Conecta tu cliente MCP

Cada cliente necesita la ruta absoluta a dist/index.js. Desde dentro del repositorio:

pwd   # e.g. /Users/you/projects/unc-libcal-mcp
# Use: <that-path>/dist/index.js

O en una sola línea:

node -e "const p=require('path'); console.log(p.join(process.cwd(),'dist/index.js'))"

Todos los clientes siguientes ejecutan el mismo servidor stdio:

{
  "command": "node",
  "args": ["/absolute/path/to/unc-libcal-mcp/dist/index.js"]
}

Reinicia el cliente después de editar la configuración.

Claude Desktop

Archivo: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "unc-libcal": {
      "command": "node",
      "args": ["/absolute/path/to/unc-libcal-mcp/dist/index.js"]
    }
  }
}

Cierra y vuelve a abrir Claude Desktop por completo.

Cursor

Opción A — Interfaz: Settings → MCP → Add server → pega el bloque JSON de arriba.

Opción B — archivo de proyecto: .cursor/mcp.json en este repositorio (útil para compartir con compañeros):

{
  "mcpServers": {
    "unc-libcal": {
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

Usa ./dist/index.js solo si el directorio de trabajo MCP de Cursor es la raíz del proyecto; de lo contrario, usa la ruta absoluta.

OpenAI Codex (CLI)

Codex usa TOML, no JSON. Archivo: ~/.codex/config.toml (o .codex/config.toml en un proyecto de confianza).

[mcp_servers.unc-libcal]
command = "node"
args = ["/absolute/path/to/unc-libcal-mcp/dist/index.js"]

O mediante CLI:

codex mcp add unc-libcal -- node /absolute/path/to/unc-libcal-mcp/dist/index.js
codex mcp list   # verify it appears

Si los servidores no aparecen, confirma que el proyecto es de confianza (ejecuta codex trust en el repositorio) cuando uses un .codex/config.toml local del proyecto.

Claude Code (CLI)

Archivo: ~/.claude.json (global) o .mcp.json en el proyecto:

{
  "mcpServers": {
    "unc-libcal": {
      "command": "node",
      "args": ["/absolute/path/to/unc-libcal-mcp/dist/index.js"]
    }
  }
}

En una sesión de Claude Code, ejecuta /mcp para confirmar que las herramientas están cargadas.

Otros clientes MCP

Cualquier cliente que admita stdio MCP puede usar los mismos command + args. Configúralo para que apunte a dist/index.js después de npm run build.

5. Verifica que funciona

En tu agente, prueba:

Check libcal auth status

Luego:

Suggest Davis cubes for 2 hours tomorrow

Deberías ver libcal_auth_status, libcal_suggest, libcal_check_availability, libcal_book y libcal_list_calendars disponibles una vez que el servidor esté conectado.

Herramientas MCP

Flujo de reserva

1. Para solicitudes abiertas («reserva un cubículo», «máximo de horas») → el agente llama primero a libcal_suggest

2. El agente muestra opciones numeradas; tú eliges una

3. El agente llama a libcal_book con user_confirmed: true y la fecha/hora elegida

libcal_book no se ejecutará sin confirmación explícita.

Categorías de espacios

Ejemplos de prompts

Book me a study room for as long as possible
→ libcal_suggest shows TODAY vs later; you pick; then libcal_book

Book me a Davis cube tomorrow 11am–1pm
→ libcal_suggest or direct libcal_book with your exact time

Any study rooms free Friday afternoon?
→ libcal_check_availability or libcal_suggest

Cómo funciona

• Disponibilidad — API de cuadrícula de LibCal obtenida mediante ingeniería inversa (/spaces/availability/grid)

• Reserva — Playwright maneja la interfaz real de LibCal: selecciona un espacio → envía los horarios → checkout en /spaces/auth → confirma el formulario

• Calendario — AppleScript → Calendar.app (requiere permiso de Automatización de macOS)

Las sesiones caducan periódicamente. Ejecuta npm run login de nuevo cuando libcal_auth_status indique que ha caducado.

Scripts de CLI

# Refresh Onyen session
npm run login

# Run unit tests (38 tests)
npm test

# Book via CLI (uses saved session)
node dist/scripts/run-task.js --date 2026-09-01 --start 14:00 --duration 120

# Check public bookings page / cancel-link availability
node dist/scripts/list-bookings.js

Cancelar reservas

UNC LibCal no expone una página de cancelación de «mis reservas» en la interfaz web. Cancela mediante el enlace del correo de confirmación de alerts@mail.libcal.com.

Límites de LibCal (UNC Davis)

• Hasta 3 horas al día, en segmentos de 30 minutos / 1 hora

• Los espacios populares pueden ocuparse entre la sugerencia y la reserva

• Los cubículos pueden requerir un «nombre de curso o grupo» en el formulario de checkout (por defecto, bookingPurpose en la configuración)

Desarrollo

npm run build    # compile TypeScript → dist/
npm test         # unit + integration tests
npm run dev      # build and start MCP server on stdio

Advertencias

• Herramienta de automatización personal: úsala con responsabilidad y sigue las políticas de UNC Library

• Solo probada con calendar.lib.unc.edu (UNC Chapel Hill)

• Otras instituciones de LibCal necesitarían constantes lid/gid diferentes en src/libcal/constants.ts

Licencia

MIT — consulta LICENSE.