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.

已驗證STDIO僅桌面效率與工作流溝通與協作

概覽

AI 產生的概覽

一個本機 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 區塊中傳入這些變數。
安裝前請注意
此伺服器需要 CalDAV 帳號憑證(CALDAV_USERNAME、CALDAV_PASSWORD),並且可以建立、更新、刪除與移動行事曆事件與行事曆,因此變更會寫入真實行事曆。README 指出許多 MCP 宿主會剝除 stdio 伺服器繼承的環境變數,因此憑證必須設在宿主的每個伺服器 env 區塊中。測試時請指向一個臨時 CalDAV 帳號。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 cal-scheduler,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

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 RRULE whose anchor contradicts it (e.g. a series starting on the 30th but set to repeat on the 1st), and normalises UNTIL to UTC under a zoned DTSTART as 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:

ModuleRole
config.pyenvironment config (CALDAV_*, CAL_DEFAULT_TZ)
timezones.pyparse datetimes; naive → assume default-zone wall time, offset → normalise into the zone; report what was assumed
ical.pybuild/parse VEVENTs (icalendar), expand ranges (recurring-ical-events), recurrence validation, EXDATE/RECURRENCE-ID ops
store.pyCalDAV transport (caldav) — list/create/delete calendars, get/put/delete events, read-modify-write with etag
server.pythe FastMCP stdio server and the tool surface

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:

bash
uv tool install 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:

bash
# 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 environmentgh repo clone limey/cal-scheduler-mcpuv 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

Don't uv add cal-scheduler-mcp for the MCP — uv add writes into whatever project you're sitting in, not into the tool environment. For an MCP server (spawned as a subprocess), uv tool install is the right shape.

Configure

All configuration is via environment variables:

VariableRequiredDefaultMeaning
CALDAV_BASE_URL✅—CalDAV server URL, e.g. http://127.0.0.1:5232
CALDAV_USERNAME—CalDAV account user
CALDAV_PASSWORD—CalDAV account password
CAL_DEFAULT_TZPacific/AucklandIANA zone every event is stored in

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:

json
{  "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 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:

json
{  "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"      }    }  }}

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

bash
uv sync                 # install deps + dev toolsuv run ruff check       # lintuv run pytest           # unit tests (no server required)

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
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v1.1.3最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分