UNC LibCal MCP
UNC LibCal MCP lets you check availability, get ranked suggestions, and book UNC Davis Library study spaces through an MCP client, with optional Apple Calendar integration.
Check whether your saved UNC LibCal login session is still valid (
libcal_auth_status).Find ranked booking options with same-day priority (
libcal_suggest) for categories: Davis cubes, group study rooms, and lab computers.Check open slots on one specific date (
libcal_check_availability).Book a confirmed UNC LibCal slot (
libcal_book) after explicit user confirmation, optionally adding it to Apple Calendar.List Apple Calendar names (
libcal_list_calendars) for use in the config.Follow a guided booking workflow: suggest options first, present them to the user, then book only after the user picks one.
Note: the server cannot cancel bookings.
Adds confirmed LibCal study space bookings to Apple Calendar on macOS via AppleScript, optionally syncing reservation details to the user's chosen calendar.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@UNC LibCal MCP Book me a Davis cube tomorrow at 2pm"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
UNC LibCal MCP
MCP server for booking UNC Davis Library study spaces from Claude, Cursor, Codex, or any MCP client.
Built for UNC students, faculty, and staff with a valid Onyen. Not affiliated with or endorsed by UNC Libraries.
What it does
Ask your agent:
Book me a Davis cube tomorrow at 2pm
The server will:
Check LibCal availability (public API — no login needed)
Suggest ranked options (
libcal_suggest) or book a slot you confirm (libcal_book)Complete the reservation in your browser session (Playwright + saved Onyen login)
Related MCP server: @aiwerk/mcp-server-cal
Requirements
Node.js 20+
UNC Onyen (for booking; availability checks work without login)
Chromium (installed automatically via Playwright)
Quick start
Already on this machine?
If you already have the repo and ~/.unc-libcal/:
cd ~/Personal\ Code\ Projects/MCPs/unc-libcal-mcp
npm run build
npm test~/Personal Code Projects/MCPs/unc-libcal-mcp— the project (clone from GitHub)~/.unc-libcal/— your private session + config (never commit this)storage-state.json— saved login cookies fromnpm run login
Skip to step 2 if you've logged in before, or re-run login if booking fails.
1. Clone and install
git clone https://github.com/Thespaceblade/unc-libcal-mcp.git
cd unc-libcal-mcp
npm install
npx playwright install chromium
npm run build
npm testClaude Desktop (.mcpb)
Package for one-click install:
npm run pack:mcpbThen double-click unc-libcal-mcp.mcpb or drag it into Claude Desktop Settings. You still need to run node dist/login.js once to save your Onyen session to ~/.unc-libcal/.
2. Log in to LibCal
npm run loginA browser opens to the Davis cubes page (this is normal — the calendar is public and does not ask for Onyen immediately).
The script auto-clicks a test slot and opens UNC Onyen. Sign in (+ Duo if prompted).
You may land on Booking Details with a held test slot — that is normal. Do not click "Submit my Booking".
Press Enter in the terminal. The script clears the held slot and returns you to the Davis cubes calendar where Logout should appear.
Your session is saved to ~/.unc-libcal/storage-state.json (never commit this file).
3. Configure (optional)
On first run, ~/.unc-libcal/config.json is created with defaults:
{
"defaultCategory": "davis-cubes",
"preferSameDay": true,
"minLeadMinutes": 30,
"searchHorizonDays": 7,
"bookingPurpose": "Study session"
}4. Connect your MCP client
Every client needs the absolute path to dist/index.js. From inside the repo:
pwd # e.g. /Users/you/projects/unc-libcal-mcp
# Use: <that-path>/dist/index.jsOr one-liner:
node -e "const p=require('path'); console.log(p.join(process.cwd(),'dist/index.js'))"All clients below run the same stdio server:
{
"command": "node",
"args": ["/absolute/path/to/unc-libcal-mcp/dist/index.js"]
}Restart the client after editing config.
Claude Desktop
File: ~/Library/Application Support/Claude/claude_desktop_config.json
If the file is new or empty, paste:
{
"mcpServers": {
"unc-libcal": {
"command": "node",
"args": ["/absolute/path/to/unc-libcal-mcp/dist/index.js"]
}
}
}If the file already has other keys (e.g. preferences, coworkUserFilesPath), add only the unc-libcal block inside the existing mcpServers object — do not replace the whole file.
Fully quit and reopen Claude Desktop (Cmd+Q, not just closing the window).
Cursor
Option A — UI: Settings → MCP → Add server → paste the JSON block above.
Option B — project file: .cursor/mcp.json in this repo (good for sharing with teammates):
{
"mcpServers": {
"unc-libcal": {
"command": "node",
"args": ["./dist/index.js"]
}
}
}Use ./dist/index.js only if Cursor's MCP cwd is the project root; otherwise use the absolute path.
OpenAI Codex (CLI)
Codex uses TOML, not JSON. File: ~/.codex/config.toml (or .codex/config.toml in a trusted project).
[mcp_servers.unc-libcal]
command = "node"
args = ["/absolute/path/to/unc-libcal-mcp/dist/index.js"]Or via CLI:
codex mcp add unc-libcal -- node /absolute/path/to/unc-libcal-mcp/dist/index.js
codex mcp list # verify it appearsIf servers don't show up, confirm the project is trusted (codex trust in the repo) when using a project-local .codex/config.toml.
Claude Code (CLI)
File: ~/.claude.json (global) or .mcp.json in the project:
{
"mcpServers": {
"unc-libcal": {
"command": "node",
"args": ["/absolute/path/to/unc-libcal-mcp/dist/index.js"]
}
}
}In a Claude Code session, run /mcp to confirm tools are loaded.
Other MCP clients
Any client that supports stdio MCP can use the same command + args. Point it at dist/index.js after npm run build.
5. Verify it works
In your agent, try:
Check libcal auth statusThen:
Suggest Davis cubes for 2 hours tomorrowYou should see libcal_auth_status, libcal_suggest, libcal_check_availability, and libcal_book available once the server is connected.
Troubleshooting
Problem | Fix |
| Wait — the script auto-clicks a slot and Submit Times to reach Onyen |
| Run |
Session expires quickly | Normal for UNC SSO — re-run |
Login saved but booking redirects to SSO | Re-run |
| Slot was taken — run |
MCP tools don't appear in Claude Desktop | Fully quit (Cmd+Q) and reopen; confirm |
Sessions expire periodically (LibCal auth ~24h; UNC SSO sooner with inactivity). Run npm run login again when libcal_auth_status reports expired.
MCP tools
Tool | Login required | Purpose |
| No | Ranked booking options; same-day priority unless you specify a date |
| No | Open slots on one date |
| Yes | Book a confirmed slot |
| Yes | Check if saved session is still valid |
Booking workflow
For open-ended requests (“book a cube”, “max hours”) → agent calls
libcal_suggestfirstAgent shows numbered options; you pick one
Agent calls
libcal_bookwithuser_confirmed: trueand the chosen date/time
libcal_book will not run without explicit confirmation.
Space categories
ID | Description |
| Davis Collaboration Cubes (default) |
| Davis group study rooms |
| Data Services lab computers |
Example 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_suggestHow it works
Availability — reverse-engineered LibCal grid API (
/spaces/availability/grid)Booking — Playwright drives the real LibCal UI: select slot → submit times →
/spaces/authcheckout → confirm form
CLI scripts
# Refresh Onyen session
npm run login
# Run unit tests (46 tests)
npm test
# Book via CLI (uses saved session)
node dist/scripts/run-task.js --date 2026-09-01 --start 14:00 --duration 120Cancelling bookings
This MCP server cannot cancel reservations. LibCal does not expose cancel links in the web UI or any API we can call.
To cancel, use the link in your confirmation email from alerts@mail.libcal.com. Search your inbox for that sender if you need an old booking.
LibCal limits (UNC Davis)
Up to 3 hours per day, in 30-minute / 1-hour segments
Popular slots can be taken between suggest and book
Cubes may require a “course or group name” on the checkout form (defaults to
bookingPurposein config)
Development
npm run build # compile TypeScript → dist/
npm test # unit + integration tests
npm run dev # build and start MCP server on stdioSee CONTRIBUTING.md for setup details, project layout, PR expectations, and how to report bugs.
Contributing
Issues and PRs are welcome. For anything beyond a small docs/test fix, open an issue first so we can agree on the approach.
Fork (or branch) →
npm install→npx playwright install chromium→npm testKeep changes focused; add tests for behavior changes
Never commit
~/.unc-libcal/session files or credentials
Caveats
Personal automation tool — use responsibly and follow UNC Library policies
Only tested against
calendar.lib.unc.edu(UNC Chapel Hill)Other LibCal institutions would need different
lid/gidconstants insrc/libcal/constants.ts
License
MIT — see LICENSE.
Available Tools
5 toolslibcal_auth_statusA
Check whether your saved UNC LibCal login session is still valid. Run npm run login in the unc-libcal-mcp project if expired.
Inputs: no named parameters.
libcal_bookA
Book a specific UNC LibCal slot. BOOKING WORKFLOW (required):
For open-ended requests ("book a room", "max hours", "soonest available") → call libcal_suggest FIRST.
Present numbered options to the user. Explain the recommended option (usually same-day if available).
Only call libcal_book after the user picks an option (or gives explicit date+time).
Never auto-book a far-future date when sooner options exist. Requires user_confirmed=true. Categories: davis-cubes, davis-study-rooms, davis-computers
Inputs: date (required), start_time (required), user_confirmed (required), duration_minutes (required), +3 more.
libcal_check_availabilityA
Check open slots on ONE specific date. For smart ranked search across days, use libcal_suggest instead. Categories: davis-cubes, davis-study-rooms, davis-computers
Inputs: date (required), category, after_time, duration_minutes.
libcal_list_calendarsA
List Apple Calendar calendar names (use one in ~/.unc-libcal/config.json as calendarName).
Inputs: no named parameters.
libcal_suggestA
Find ranked booking options with same-day priority. Use BEFORE booking when the user has not given an exact date+time. BOOKING WORKFLOW (required):
For open-ended requests ("book a room", "max hours", "soonest available") → call libcal_suggest FIRST.
Present numbered options to the user. Explain the recommended option (usually same-day if available).
Only call libcal_book after the user picks an option (or gives explicit date+time).
Never auto-book a far-future date when sooner options exist. Categories: davis-cubes, davis-study-rooms, davis-computers
Inputs: category, max_options, preferred_date, prefer_same_day, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
The core booking tools are clearly separated: check_availability is for a single date, suggest is for ranked multi-day searching, and book handles the actual reservation. Support tools like auth_status and list_calendars are distinct, though check_availability and suggest could still cause minor confusion without their descriptions.
All tools share the libcal_ prefix and snake_case, but the patterns are mixed: some are verb_noun (check_availability, list_calendars), some are bare verbs (book, suggest), and one is noun_noun (auth_status). This is readable but not fully consistent.
Five tools is a well-scoped set for a library booking server. Each tool serves a distinct role: availability checking, ranked suggestions, booking, authentication status, and calendar configuration.
The server covers finding and booking slots but lacks obvious lifecycle operations like listing existing bookings or cancelling a booking. Users or agents needing to modify or cancel a reservation would hit a dead end, which is a significant gap for a booking-focused server.
Maintenance
Related MCP Connectors
Connects ChatGPT to your Apple Calendar via a local Mac agent + Vercel relay
Calendar API for AI agents: events, availability, Google/Microsoft setup, scheduling, and iCal.
Manage Bookla bookings, availability, services, resources and clients with AI agents.
Scheduling infrastructure for AI agents across Google and Microsoft calendars.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables interaction with the DiSH room booking platform to search availability, create bookings, and manage reservations. It allows AI assistants to handle meeting room logistics directly through natural language commands.3-

@aiwerk/mcp-server-calofficial
AlicenseAqualityCmaintenanceConnects AI assistants to Cal.com for managing bookings, event types, and availability through natural language.1250 npmMIT- FlicenseBqualityDmaintenanceEnables natural language booking and management of rooms in Nexudus coworking spaces, including listing rooms, checking availability, booking, viewing/cancelling bookings, and schedules.6-
- AlicenseNot gradedqualityDmaintenanceExposes Cal.com scheduling tools to AI agents via MCP, enabling listing event types, checking availability, and managing bookings (create, cancel, reschedule).67 npmMIT