UNC LibCal MCP

用于从 Claude、Cursor、Codex 或任何 MCP 客户端预订 UNC Davis Library 学习空间的 MCP 服务器——可选集成 Apple Calendar。

专为拥有有效 Onyen 的 UNC 学生、教职员工打造。与 UNC Libraries 无关联，亦未获其认可。

功能

向你的智能体提问：

帮我订明天下午 2 点的 Davis 隔间

服务器将：

1. 检查 LibCal 可用性（公共 API——无需登录）

2. 推荐排序选项（libcal_suggest），或预订你确认的时段（libcal_book）

3. 在你的浏览器会话中完成预订（Playwright + 已保存的 Onyen 登录）

4. 可选：将事件添加到 Apple Calendar（仅 macOS）

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

环境要求

• Node.js 20+

• UNC Onyen（预订需要；可用性检查无需登录）

• macOS（用于 Apple Calendar 同步，可选）

• Chromium（通过 Playwright 自动安装）

快速开始

1. 克隆并安装

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. 登录 LibCal

npm run login

浏览器打开 → 使用你的 Onyen 登录（如有提示还需 Duo）→ 当 Davis LibCal 页面加载完成后，在终端中按 Enter。

你的会话将保存到 ~/.unc-libcal/storage-state.json（切勿提交此文件）。

3. 配置（可选）

首次运行时，将创建 ~/.unc-libcal/config.json，包含默认值：

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

让智能体运行 libcal_list_calendars，然后将 calendarName 设置为你偏好的 Apple Calendar。当 macOS 提示时，授予 Automation 权限（Terminal 或 Cursor → Calendar）。

4. 连接你的 MCP 客户端

每个客户端都需要 dist/index.js 的绝对路径。在仓库内运行：

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

或单行命令：

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

以下所有客户端都运行相同的 stdio 服务器：

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

编辑配置后请重启客户端。

Claude Desktop

文件：~/Library/Application Support/Claude/claude_desktop_config.json

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

完全退出并重新打开 Claude Desktop。

Cursor

选项 A — 界面操作： Settings → MCP → Add server → 粘贴上面的 JSON 块。

选项 B — 项目文件： 本仓库中的 .cursor/mcp.json（便于与团队成员共享）：

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

仅当 Cursor 的 MCP 工作目录为项目根目录时使用 ./dist/index.js；否则请使用绝对路径。

OpenAI Codex（CLI）

Codex 使用 TOML 而非 JSON。文件：~/.codex/config.toml（或受信任项目中的 .codex/config.toml）。

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

或通过 CLI：

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

如果服务器未显示，请确认在使用项目级 .codex/config.toml 时项目已被信任（在仓库中运行 codex trust）。

Claude Code（CLI）

文件：~/.claude.json（全局）或项目中的 .mcp.json：

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

在 Claude Code 会话中，运行 /mcp 确认工具已加载。

其他 MCP 客户端

任何支持 stdio MCP 的客户端都可以使用相同的 command + args。在 npm run build 之后将其指向 dist/index.js。

5. 验证是否正常工作

在你的智能体中尝试：

Check libcal auth status

然后：

Suggest Davis cubes for 2 hours tomorrow

服务器连接后，你应该会看到 libcal_auth_status、libcal_suggest、libcal_check_availability、libcal_book 和 libcal_list_calendars 可用。

MCP 工具

预订流程

1. 对于开放式请求（"订一个隔间"、"最长时长"）→ 智能体首先调用 libcal_suggest

2. 智能体显示编号选项；你选择一个

3. 智能体以 user_confirmed: true 和所选日期/时间调用 libcal_book

未经明确确认，libcal_book 不会运行。

空间类别

示例提示

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

工作原理

• 可用性 — 逆向工程的 LibCal 网格 API（/spaces/availability/grid）

• 预订 — Playwright 驱动真实的 LibCal 界面：选择时段 → 提交时间 → /spaces/auth 结账 → 确认表单

• 日历 — AppleScript → Calendar.app（需要 macOS Automation 权限）

会话会定期过期。当 libcal_auth_status 报告已过期时，重新运行 npm run login。

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

取消预订

UNC LibCal 不在 Web 界面中提供"我的预订"取消页面。请通过 alerts@mail.libcal.com 发送的确认邮件中的链接取消。

LibCal 限制（UNC Davis）

• 每天最多 3 小时，以 30 分钟 / 1 小时为分段

• 热门时段可能在建议和预订之间被抢走

• 隔间在结账表单上可能需要填写"课程或小组名称"（默认为配置中的 bookingPurpose）

开发

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

注意事项

• 个人自动化工具——请负责任地使用并遵守 UNC Library 政策

• 仅针对 calendar.lib.unc.edu（UNC Chapel Hill）测试

• 其他 LibCal 机构需要在 src/libcal/constants.ts 中使用不同的 lid/gid 常量

许可证

MIT — 参见 LICENSE。