UNC LibCal MCP

MCP-Server zur Buchung von UNC Davis Library Lernräumen über Claude, Cursor, Codex oder einen beliebigen MCP-Client – mit optionaler Apple-Kalender-Integration.

Entwickelt für UNC-Studierende, Dozierende und Mitarbeitende mit gültigem Onyen. Nicht verbunden mit oder unterstützt von UNC Libraries.

Was es tut

Fragen Sie Ihren Agenten:

Buche mir morgen um 14 Uhr einen Davis-Cube

Der Server wird:

1. LibCal-Verfügbarkeit prüfen (öffentliche API – keine Anmeldung erforderlich)

2. Rangfolge-Optionen vorschlagen (libcal_suggest) oder einen von Ihnen bestätigten Slot buchen (libcal_book)

3. Die Reservierung in Ihrer Browser-Sitzung abschließen (Playwright + gespeicherter Onyen-Login)

4. Optional das Ereignis zum Apple-Kalender hinzufügen (nur macOS)

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

Voraussetzungen

• Node.js 20+

• UNC Onyen (für Buchungen; Verfügbarkeitsprüfungen funktionieren ohne Anmeldung)

• macOS für die Apple-Kalender-Synchronisierung (optional)

• Chromium (wird automatisch über Playwright installiert)

Schnellstart

1. Klonen und installieren

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. Bei LibCal anmelden

npm run login

Ein Browser öffnet sich → melden Sie sich mit Ihrem Onyen an (+ Duo, falls aufgefordert) → sobald die Davis-LibCal-Seite geladen ist, drücken Sie Enter im Terminal.

Ihre Sitzung wird unter ~/.unc-libcal/storage-state.json gespeichert (diese Datei niemals committen).

3. Konfigurieren (optional)

Beim ersten Start wird ~/.unc-libcal/config.json mit Standardwerten erstellt:

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

Bitten Sie den Agenten, libcal_list_calendars auszuführen, und setzen Sie dann calendarName auf Ihren bevorzugten Apple-Kalender. Erteilen Sie die Automation-Berechtigung, wenn macOS dazu auffordert (Terminal oder Cursor → Kalender).

4. MCP-Client verbinden

Jeder Client benötigt den absoluten Pfad zu dist/index.js. Von innerhalb des Repos:

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

Oder als Einzeiler:

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

Alle unten genannten Clients verwenden denselben stdio-Server:

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

Starten Sie den Client nach der Konfigurationsänderung neu.

Claude Desktop

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

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

Beenden Sie Claude Desktop vollständig und öffnen Sie es erneut.

Cursor

Option A – Benutzeroberfläche: Einstellungen → MCP → Server hinzufügen → den obigen JSON-Block einfügen.

Option B – Projektdatei: .cursor/mcp.json in diesem Repo (gut zum Teilen mit Teammitgliedern):

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

Verwenden Sie ./dist/index.js nur, wenn das MCP-Arbeitsverzeichnis von Cursor das Projektverzeichnis ist; andernfalls den absoluten Pfad verwenden.

OpenAI Codex (CLI)

Codex verwendet TOML, nicht JSON. Datei: ~/.codex/config.toml (oder .codex/config.toml in einem vertrauenswürdigen Projekt).

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

Oder über die CLI:

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

Wenn Server nicht angezeigt werden, stellen Sie sicher, dass das Projekt vertrauenswürdig ist (codex trust im Repo), wenn Sie eine projektlokale .codex/config.toml verwenden.

Claude Code (CLI)

Datei: ~/.claude.json (global) oder .mcp.json im Projekt:

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

Führen Sie in einer Claude-Code-Sitzung /mcp aus, um zu bestätigen, dass die Tools geladen sind.

Andere MCP-Clients

Jeder Client, der stdio MCP unterstützt, kann dieselben command + args verwenden. Zeigen Sie nach npm run build auf dist/index.js.

5. Funktion überprüfen

Versuchen Sie in Ihrem Agenten:

Check libcal auth status

Dann:

Suggest Davis cubes for 2 hours tomorrow

Sie sollten libcal_auth_status, libcal_suggest, libcal_check_availability, libcal_book und libcal_list_calendars sehen, sobald der Server verbunden ist.

MCP-Tools

Buchungsablauf

1. Bei offenen Anfragen („einen Cube buchen“, „maximale Stunden“) → Agent ruft zuerst libcal_suggest auf

2. Agent zeigt nummerierte Optionen; Sie wählen eine aus

3. Agent ruft libcal_book mit user_confirmed: true und dem gewählten Datum/der gewählten Uhrzeit auf

libcal_book wird ohne ausdrückliche Bestätigung nicht ausgeführt.

Raumkategorien

Beispiel-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

So funktioniert es

• Verfügbarkeit – Reverse-Engineering der LibCal-Grid-API (/spaces/availability/grid)

• Buchung – Playwright steuert die echte LibCal-Oberfläche: Slot auswählen → Zeiten übermitteln → /spaces/auth-Checkout → Bestätigungsformular

• Kalender – AppleScript → Kalender.app (macOS-Automation-Berechtigung erforderlich)

Sitzungen laufen regelmäßig ab. Führen Sie npm run login erneut aus, wenn libcal_auth_status als abgelaufen meldet.

CLI-Skripte

# 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

Buchungen stornieren

UNC LibCal bietet keine „Meine Buchungen“-Stornierungsseite in der Weboberfläche. Stornieren Sie über den Link in Ihrer Bestätigungs-E-Mail von alerts@mail.libcal.com.

LibCal-Grenzen (UNC Davis)

• Bis zu 3 Stunden pro Tag, in 30-Minuten-/1-Stunden-Segmenten

• Beliebte Slots können zwischen Vorschlag und Buchung vergeben werden

• Cubes können ein „Kurs- oder Gruppenname“-Feld im Checkout-Formular erfordern (Standard: bookingPurpose in der Konfiguration)

Entwicklung

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

Einschränkungen

• Persönliches Automatisierungstool – nutzen Sie es verantwortungsbewusst und befolgen Sie die Richtlinien der UNC-Bibliothek

• Nur gegen calendar.lib.unc.edu (UNC Chapel Hill) getestet

• Andere LibCal-Einrichtungen benötigen andere lid/gid-Konstanten in src/libcal/constants.ts

Lizenz

MIT – siehe LICENSE.