cal-scheduler

この MCP をインストールするエージェントは、まず AGENTS.md をお読みください。

cal-scheduler

あらゆる CalDAV カレンダーのスケジュール管理に対応した、薄くてタイムゾーンを正しく扱うMCP サーバーです。 LLM エージェントに小規模で厳格なカレンダーツール一式を提供し、モデルに任せる必要がない iCalendar の決定的で扱いにくい処理を正しく実行します。

これは NLP レイヤーではありません。エージェントがリクエストを表現し、サーバーが検証して、不正な入力を明確に拒否し、タイムゾーン情報を保持したクリーンな .ics を保存します。

開発の背景

LLM が利用する一般的なカレンダーツールは、微妙な点で3つの誤りを犯しがちです。cal-scheduler は、設計上これらの問題を解決します。

• 単なる UTC ではなく、タイムゾーン付きで保存します。 イベントは TZID／VTIMEZONE 付きで書き込まれるため、夏時間の切り替わりを挟んでも、毎週午前9時の予定が午前9時のまま維持され、1時間ずれることはありません。単なる UTC で保存することが、このずれの典型的な原因です。
• 繰り返しを検証します。 起点と矛盾する RRULE（たとえば、30日に開始する予定なのに1日に繰り返す設定）を拒否し、RFC 5545 の要件に従って、タイムゾーン付きの DTSTART に対する UNTIL を UTC に正規化します。
• 単一の予定に対する編集を正しく実行します。 繰り返し全体に影響を与えずに、1回分を除外（EXDATE）したり、1回分を移動（RECURRENCE-ID）したりできます。素朴なラッパーでは、こうした操作ができないことがよくあります。

動作の仕組み

カレンダーエンジンを独自に実装するのではなく、成熟したライブラリを組み合わせた小規模な uv Python パッケージです。

モジュール	役割
config.py	環境設定（CALDAV_*、CAL_DEFAULT_TZ）
timezones.py	日時を解析します。タイムゾーン情報がない場合はデフォルトのタイムゾーンの現地時刻として扱い、オフセットがある場合はそのタイムゾーンに正規化して、どのように解釈したかを報告します
ical.py	VEVENT の作成／解析（icalendar）、期間の展開（recurring-ical-events）、繰り返しの検証、EXDATE／RECURRENCE-ID 操作
store.py	CalDAV 通信（caldav）— カレンダーの一覧表示／作成／削除、イベントの取得／登録／削除、etag を使った読み取り・変更・書き戻し
server.py	FastMCP の stdio サーバーとツール群

MCP ホスト（Claude、エージェント用ハーネスなど）がサブプロセスとして起動する stdio MCP サーバーとして動作します。

インストール

Python ≥ 3.11 が必要です。パッケージは PyPI で cal-scheduler-mcp として公開されています。

uv tool install cal-scheduler-mcp

（または pip install cal-scheduler-mcp、uvx --from cal-scheduler-mcp cal-scheduler など）

編集可能な開発環境として使う場合は、クローンからインストールします。

# run straight from the repo with uv (no global install)
uv run --directory /path/to/cal-scheduler-mcp cal-scheduler

# or install the console script into a tool environment
gh repo clone limey/cal-scheduler-mcp
uv tool install --editable /path/to/cal-scheduler-mcp
# or, with SSH GitHub access, in one step:
uv tool install git+ssh://[email protected]/limey/cal-scheduler-mcp

MCP 用に uv add cal-scheduler-mcp を実行しないでください。uv add は、ツール環境ではなく、現在いるプロジェクトに書き込みます。サブプロセスとして起動する MCP サーバーには、uv tool install が適切です。

設定

すべての設定は環境変数で行います。

変数	必須	デフォルト	説明
CALDAV_BASE_URL	✅	—	CalDAV サーバーの URL。例：http://127.0.0.1:5232
CALDAV_USERNAME		—	CalDAV アカウントのユーザー名
CALDAV_PASSWORD		—	CalDAV アカウントのパスワード
CAL_DEFAULT_TZ		Pacific/Auckland	すべてのイベントの保存に使用する IANA タイムゾーン

多くの MCP ホストは stdio サーバーから継承した環境変数を取り除くため、シェル環境に依存せず、ホストのサーバーごとの env ブロックで設定してください。

MCP ホストの設定例

MCP は、ホストが起動する stdio サブプロセスとして実行されます。多くのホストは、そのサブプロセスから継承される PATH を削除するため、起動するホストの PATH に cal-scheduler の shim があることを前提とせず、uv run --directory 形式を使用してください。

{
  "mcpServers": {
    "cal-scheduler": {
      "command": "uv",
      "args": ["run", "--directory", "/abs/path/to/cal-scheduler-mcp", "cal-scheduler"],
      "env": {
        "CALDAV_BASE_URL": "http://127.0.0.1:5232",
        "CALDAV_USERNAME": "me",
        "CALDAV_PASSWORD": "secret",
        "CAL_DEFAULT_TZ": "Pacific/Auckland"
      }
    }
  }
}

/abs/path/to/cal-scheduler-mcp は、このリポジトリをローカルにクローンした場所の絶対パスです（上記の インストール を参照）。

PyPI から uv tool install cal-scheduler-mcp でインストールした場合は、インストール済みの shim を直接使用してください。

{
  "mcpServers": {
    "cal-scheduler": {
      "command": "/path/to/cal-scheduler",
      "env": {
        "CALDAV_BASE_URL": "http://127.0.0.1:5232",
        "CALDAV_USERNAME": "me",
        "CALDAV_PASSWORD": "secret",
        "CAL_DEFAULT_TZ": "Pacific/Auckland"
      }
    }
  }
}

which cal-scheduler または uv tool list --show-paths で shim のパスを確認してください。

任意の CalDAV サーバーと組み合わせてください。セルフホスト可能な簡単な選択肢として、Radicale があります（ローカルでの使用では、TLS 不要の通常の http:// を使用します）。

ツール一覧

イベント — list_events(start, end, [calendar])、create_event(summary, start, [end, calendar, description, location, rrule])、update_event(uid, …)、 delete_event(uid, [calendar])、exclude_occurrence(uid, occurrence, [calendar])、 move_occurrence(uid, occurrence, new_start, [new_end, calendar])、 mark_done(uid, [calendar]) — イベントに完了タグを付け、タイムスタンプを記録します。

カレンダー — list_calendars、create_calendar(name)、delete_calendar(name)。

ヘルパー — resolve_datetime(value) — 何も書き込まずに、日時がどのように解釈されるかをプレビューします。

タイムゾーンのルール（このツールの要点）

すべてのイベントは CAL_DEFAULT_TZ のタイムゾーンで保存されます。

• タイムゾーン情報のない日時（2026-06-30T21:00）は、そのタイムゾーンの現地時刻として扱われ、ツールの応答でその旨が示されます（"assumed Pacific/Auckland wall time"）。
• UTC オフセット付きの日時（…+12:00）は、指定された時点として扱われ、そのタイムゾーンで表し直されます。オフセットが一致する場合は同じ時刻となり、一致しない場合は正しく変換されます。
• 日付のみの値（2026-06-30）は、終日のイベントになります。

開発

uv sync                 # install deps + dev tools
uv run ruff check       # lint
uv run pytest           # unit tests (no server required)

ユニットテストでは、タイムゾーン解決、繰り返しの検証、EXDATE/RECURRENCE-ID の構築といった純粋なレイヤーを対象としており、稼働中の CalDAV サーバーは必要ありません。スタック全体をエンドツーエンドでテストするには、一時的な CalDAV アカウントを CALDAV_BASE_URL に指定してください。

ライセンス

MIT © 2026 Robert Clark