UNC LibCal MCP

Claude、Cursor、Codex、または任意のMCPクライアントからUNC Davis Libraryの学習スペースを予約するためのMCPサーバー — Apple Calendar連携オプション付き。

有効なOnyenを持つUNCの学生、教員、スタッフ向けに構築されています。UNC Librariesとは提携しておらず、その承認も受けていません。

機能

エージェントに依頼：

明日の午後2時にDavis cubeを予約して

サーバーは次のことを行います：

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 — UI： 設定 → MCP → サーバーを追加 → 上記のJSONブロックを貼り付けます。

オプションB — プロジェクトファイル： このリポジトリ内の.cursor/mcp.json（チームメイトと共有するのに便利）：

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

./dist/index.jsを使用するのは、CursorのMCPのcwdがプロジェクトルートの場合のみです。それ以外の場合は絶対パスを使用してください。

OpenAI Codex (CLI)

CodexはJSONではなくTOMLを使用します。ファイル：~/.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. 自由形式のリクエスト（「cubeを予約」「最大時間」）の場合 → エージェントは最初に**libcal_suggest**を呼び出します

2. エージェントが番号付きのオプションを表示し、1つ選択します

3. エージェントは**libcal_book**をuser_confirmed: trueと選択した日時で呼び出します

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 UIを操作：スロット選択 → 時間を送信 → /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 UIには「マイ予約」のキャンセルページはありません。alerts@mail.libcal.comからの確認メールに記載されたリンクからキャンセルしてください。

LibCalの制限（UNC Davis）

• 1日最大3時間まで、30分 / 1時間単位

• 人気の枠はsuggestとbookの間に取られる可能性があります

• キューブではチェックアウトフォームに「コース名またはグループ名」が必要な場合があります（configの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を参照してください。