
cal-scheduler
io.github.limey由 GitHub 帳號 limey 發布v1.1.3更新於 Oct 24, 2026
Timezone-correct CalDAV scheduling MCP server with validated recurrence and single-occurrence edits.
概覽
一個本機 MCP 伺服器,讓助理以正確的時區與重複規則讀寫任意 CalDAV 行事曆中的事件。
- 可以做什麼
- 提供一組精簡而嚴格的行程工具:列出、建立、更新與刪除事件,列出、建立與刪除行事曆,排除或移動重複系列中的單一實例,以及將事件標記為完成。事件以設定的 IANA 時區儲存,帶有 TZID/VTIMEZONE,並驗證重複規則、依 RFC 5545 將 UNTIL 正規化為 UTC。另有一個輔助工具可在不寫入任何內容的情況下預覽日期時間將如何被解讀。
- 適用情境
- 當助理需要針對 CalDAV 行事曆安排行程且時區正確性很重要時使用,例如跨日光節約時間仍維持當地鐘面時間的重複會議,或修改重複系列中的某一次。它是驗證與持久化層,不是自然語言解析層,請求由代理來表述。
- 執行需求
- 以 stdio 子程序在本機執行;需要 Python 3.11 或更新版本以及 PyPI 套件 cal-scheduler-mcp,通常以 uv tool install 安裝或以 uvx 執行。透過環境變數設定:CALDAV_BASE_URL 為必填,CALDAV_USERNAME、CALDAV_PASSWORD 與 CAL_DEFAULT_TZ 為選填。需要能連線至 CalDAV 伺服器的網路,且宿主需在其每個伺服器的 env 區塊中傳入這些變數。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 cal-scheduler,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
If you are an agent installing this MCP, read AGENTS.md first.
cal-scheduler
[cal-scheduler-mcp MCP server]
A thin, timezone-correct MCP server for scheduling against any CalDAV calendar. It gives an LLM agent a small, strict set of calendar tools and does the deterministic, fiddly parts of iCalendar correctly so the model doesn't have to.
It is not an NLP layer: the agent phrases the request, the server validates
it, rejects bad input loudly, and persists clean zoned .ics.
Why it exists
Most calendar tooling an LLM reaches for gets three things subtly wrong. cal-scheduler fixes them by construction:
- Stores zoned, not bare UTC. Events are written with
TZID/VTIMEZONE, so a weekly 9am stays 9am across a daylight-saving boundary instead of drifting an hour. Storing bare UTC is the classic cause of that drift. - Validates recurrence. It rejects an
RRULEwhose anchor contradicts it (e.g. a series starting on the 30th but set to repeat on the 1st), and normalisesUNTILto UTC under a zonedDTSTARTas RFC 5545 requires. - Does real single-occurrence edits. Exclude one instance (
EXDATE) or move one instance (RECURRENCE-ID) without disturbing the rest of the series — the operations naive wrappers tend to lack.
How it works
A small uv Python package that composes mature libraries rather than
implementing a calendar engine:
It runs as a stdio MCP server that an MCP host (Claude, an agent harness, etc.) spawns as a subprocess.
Install
Requires Python ≥ 3.11. The package is on PyPI as
cal-scheduler-mcp:
(or pip install cal-scheduler-mcp, uvx --from cal-scheduler-mcp cal-scheduler,
etc.)
For editable dev work, install from a clone:
Don't
uv add cal-scheduler-mcpfor the MCP —uv addwrites into whatever project you're sitting in, not into the tool environment. For an MCP server (spawned as a subprocess),uv tool installis the right shape.
Configure
All configuration is via environment variables:
Many MCP hosts strip inherited environment from stdio servers, so set these in the
host's per-server env block rather than relying on the ambient shell.
Example MCP host config
The MCP runs as a stdio subprocess that the host spawns. Many hosts strip
inherited PATH from that subprocess, so wire the uv run --directory
form rather than relying on the cal-scheduler shim being on the spawn
host's PATH:
/abs/path/to/cal-scheduler-mcp is the absolute path to a local clone of
this repo (see Install above).
If you installed from PyPI with uv tool install cal-scheduler-mcp, use the
installed shim directly:
Find the shim path with which cal-scheduler or uv tool list --show-paths.
Pair it with any CalDAV server. A simple self-hosted option is
Radicale (plain http://, no TLS needed for local use).
Tool surface
Events — 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]) — tag an event done and record the timestamp.
Calendars — list_calendars, create_calendar(name), delete_calendar(name).
Helper — resolve_datetime(value) — preview how a datetime will be interpreted,
without writing anything.
The timezone rule (the whole point)
Every event is stored zoned to CAL_DEFAULT_TZ.
- A naive datetime (
2026-06-30T21:00) is assumed to be wall time in that zone, and the tool response says so ("assumed Pacific/Auckland wall time"). - An offset-qualified datetime (
…+12:00) is honoured as an instant and re-expressed in the zone — same wall clock when the offset matches, a correct conversion otherwise. - A date-only value (
2026-06-30) is an all-day event.
Develop
The unit tests cover the pure layers (timezone resolution, recurrence validation,
EXDATE/RECURRENCE-ID construction) and need no running CalDAV server. To exercise
the full stack end to end, point CALDAV_BASE_URL at a throwaway CalDAV account.
License
MIT © 2026 Robert Clark
來源:README.md,提交 0373f85
工具
0版本歷史
1- v1.1.3最新Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分