cal-scheduler

如果你是正在安装此 MCP 的 Agent，请先阅读 AGENTS.md。

cal-scheduler

一个轻量、时区处理准确的 MCP 服务，用于通过任意 CalDAV 日历安排日程。 它为大模型 Agent 提供一组精简、严格的日历工具，并正确处理 iCalendar 中确定且繁琐的部分，无需模型操心。

它不是 NLP 层：由 Agent 表述请求，服务负责验证请求、大声拒绝无效输入，并保存格式规范且包含时区信息的 .ics 文件。

存在的意义

大模型常用的大多数日历工具在三个细节上容易出错。cal-scheduler 从设计上解决了这些问题：

• 保存带时区的信息，而非裸 UTC。 事件使用 TZID/VTIMEZONE 写入，因此每周上午 9 点的事件在跨越夏令时边界后仍保持上午 9 点，而不会偏移一小时。保存裸 UTC 是导致这种偏移的典型原因。
• 验证重复规则。 如果某个 RRULE 与其锚点矛盾（例如系列从 30 日开始，却设置为在 1 日重复），则会拒绝该规则；此外，还会按照 RFC 5545 的要求，将带时区 DTSTART 下的 UNTIL 规范化为 UTC。
• 正确编辑单个实例。 可排除某个实例（EXDATE），或移动某个实例（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 服务及其工具接口

它以stdio MCP 服务的形式运行，由 MCP 宿主（Claude、Agent 执行框架等）作为子进程启动。

安装

需要 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 块中设置这些变量，而不要依赖当前 Shell 环境。

MCP 主机配置示例

MCP 作为由主机启动的 stdio 子进程运行。许多主机会从该子进程中移除继承的 PATH，因此请使用 uv run --directory 形式，而不要依赖于 cal-scheduler shim 位于启动主机的 PATH 中：

{
  "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（使用普通的 http://，本地使用无需 TLS）。

工具概览

事件 — 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"）。
• 带偏移量的日期时间（…+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_BASE_URL 指向一个临时 CalDAV 账户。

许可证

MIT © 2026 Robert Clark