caldav-mcp

caldav-mcp

✨ 功能

• 连接到 CalDAV 服务
• 列出日历
• 列出指定时间范围内的日历事件
• 创建日历事件
• 更新日历事件
• 按 UID 删除日历事件

设置

{
  "mcpServers": {
    ...,
    "calendar": {
      "command": "npx",
      "args": [
        "caldav-mcp"
      ],
      "env": {
        "CALDAV_BASE_URL": "<CalDAV server URL>",
        "CALDAV_USERNAME": "<CalDAV username>",
        "CALDAV_PASSWORD": "<CalDAV password>"
      }
    }
  }
}

开发

快速开始

在开发模式下运行 MCP 服务并启用自动重新加载：

npm run dev

此命令将直接以监视模式运行 TypeScript 代码，并自动从 .env 加载环境变量。

手动构建

或者，你也可以将 TypeScript 编译为 JavaScript 后再运行：

1. 编译：

npx tsc

2. 运行：

node dist/index.js

可用工具

list-calendars

列出所有日历，并返回其名称和绝对 URL。将日历的 url 原样作为 calendarUrl 传递给其他工具。

参数：无

返回：

• 所有可用日历的列表

list-events

列出指定 URL 的日历中开始日期与结束日期之间的所有事件

参数：

• calendarUrl：string
• end：string — 结束日期（ISO 8601）
• start：string — 开始日期（ISO 8601）

返回：

• 给定时间范围内的事件列表，每个事件包含 uid、summary、start、end，以及可选的 description 和 location

create-event

在指定 URL 的日历中创建事件。对于全天事件，将 wholeDay 设为 true。对于单日全天事件，使用同一日历日期内的 start 和 end 日期时间；它们的时间戳不必相同。

参数：

• calendarUrl：string
• description：string（可选）
• end：string — 结束日期时间（ISO 8601）
• location：string（可选）
• recurrenceRule：object（可选）
  • byday：array of string（可选）
  • bymonth：array of number（可选）
  • bymonthday：array of number（可选）
  • count：number（可选）
  • freq：enum（DAILY | WEEKLY | MONTHLY | YEARLY）（可选）
  • interval：number（可选）
  • until：string（可选）
• start：string — 开始日期时间（ISO 8601）
• summary：string
• wholeDay：boolean（可选）— 创建全天事件

返回：

• 已创建事件的唯一 ID

update-event

更新指定 URL 的日历中的现有事件。仅修改提供的字段。对于单日全天事件，将 wholeDay 设为 true，并将 start 和 end 设为同一个日历日期。

参数：

• calendarUrl：string
• description：string（可选）
• end：string（可选）
• location：string（可选）
• recurrenceRule：object（可选）
  • byday：array of string（可选）
  • bymonth：array of number（可选）
  • bymonthday：array of number（可选）
  • count：number（可选）
  • freq：enum（DAILY | WEEKLY | MONTHLY | YEARLY）（可选）
  • interval：number（可选）
  • until：string（可选）
• start：string（可选）
• summary：string（可选）
• uid：string — 要更新事件的唯一标识符（通过 list-events 获取）
• wholeDay：boolean（可选）— 更新该事件是否为全天事件

返回：

• 已更新事件的唯一 ID

delete-event

删除指定 URL 的日历中的事件

参数：

• calendarUrl：string
• uid：string — 要删除的事件的唯一标识符（通过 list-events 获取）

返回：

• 成功删除事件时的确认消息

list-todos

列出指定 URL 的日历中的任务（VTODO）。默认仅返回未完成任务（NEEDS-ACTION 和 IN-PROCESS），并按手动顺序再按截止日期排序。使用 status 可包含已完成的任务（COMPLETED）或所有任务（ALL），并使用 limit/offset 分页浏览较长的列表。

参数：

• calendarUrl：string
• due_after：string（可选）— 仅包含截止日期为此时间或之后的任务（ISO 8601）。设置截止时间范围后，不包含未设置截止日期的任务。
• due_before：string（可选）— 仅包含截止日期为此时间或之前的任务（ISO 8601）。设置截止时间范围后，不包含未设置截止日期的任务。
• limit：number（可选）— 返回的任务数量上限（默认 50，最大 500）
• offset：number（可选）— 跳过的任务数量（默认 0）
• status：enum（OPEN | ALL | NEEDS-ACTION | COMPLETED | IN-PROCESS | CANCELLED）（可选）— 按状态筛选。OPEN（默认）= NEEDS-ACTION + IN-PROCESS；ALL = 全部；或指定确切状态（NEEDS-ACTION、COMPLETED、IN-PROCESS、CANCELLED）。

返回：

• 一个对象 { todos, total, limit, offset }，其中 total 是分页前的数量。每个 todo 包含 uid、summary、status，以及可选的 due、start、completed、description、location。

create-todo

在指定 URL 的日历中创建任务（VTODO）。仅 summary 为必填项；任务可以没有日期。使用 due 设置截止时间，使用 start 设置工作开始时间。

参数：

• calendarUrl：string
• description：string（可选）
• due：string（可选）— 截止日期时间（ISO 8601）
• location：string（可选）
• start：string（可选）— 开始日期时间（ISO 8601）
• status：enum（NEEDS-ACTION | COMPLETED | IN-PROCESS | CANCELLED）（可选）— 未提供时默认为 NEEDS-ACTION
• summary：string

返回：

• 已创建 todo 的唯一 ID

update-todo

更新指定 URL 的日历中的现有任务（VTODO）。仅修改已提供的字段。要将任务标记为已完成，建议使用 complete-todo 工具。

参数：

• calendarUrl：string
• description：string（可选）
• due：string（可选）
• location：string（可选）
• start：string（可选）
• status：enum（NEEDS-ACTION | COMPLETED | IN-PROCESS | CANCELLED）（可选）
• summary：string（可选）
• uid：string — 要更新的 todo 的唯一标识符（通过 list-todos 获取）

返回：

• 已更新 todo 的唯一 ID

complete-todo

将任务（VTODO）标记为已完成。将其状态设为 COMPLETED，并记录完成时间。

参数：

• calendarUrl：string
• uid：string — 要完成的 todo 的唯一标识符（通过 list-todos 获取）

返回：

• 已完成 todo 的唯一 ID

delete-todo

删除指定 URL 的日历中的任务（VTODO）

参数：

• calendarUrl：string
• uid：string — 要删除的 todo 的唯一标识符（通过 list-todos 获取）

返回：

• 成功删除 todo 时的确认消息

许可证

MIT