calendar-ics-events-free-busy

mcp-calendar

你的日历应用可以告诉你下周二有什么安排，却无法告诉你这一周的时间究竟花在了哪里、你同时答应了哪两件事，或者上个月的会议值多少可计费工时。此服务读取日历已导出的 .ics 文件，并回答这些问题：查询任意时间段内的事件并正确展开重复系列；合并忙碌时段，并找出工作时间内真正空闲的间隙；一次检查工作日历和个人日历中的所有时间冲突；生成只包含你选定事件的精简 .ics 文件；以及给出一场你本应计费的会议对应的准确时间条目。无需连接任何账号，也不会同步任何内容，日历文件会以纯文本形式保留在你的设备上。

由 theluckystrike 构建。

已收录于 官方 MCP Registry（io.github.theluckystrike/calendar-ics-reader-events-freebusy-conflicts）。

已收录于 AI Product Index - 提供实时远程端点 mcp.zovo.one/s/calendar，有免费套餐，无需注册。

导入日历导出的 .ics 文件，然后询问有哪些安排、什么时候有空、哪些安排有冲突。零配置，全部在本地运行。

60 秒安装

@theluckystrike/mcp-calendar 尚待发布到 npm。在此之前，可使用 .mcpb 一键安装包，或克隆并构建；以下两种方式均已验证。

一键安装（.mcpb）：从最新版本下载 calendar.mcpb，然后在 Claude Desktop 中双击： https://github.com/theluckystrike/mcp-servers/releases/latest

（claude_desktop_config.json）：

{
  "mcpServers": {
    "calendar": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-calendar"]
    }
  }
}

Claude Code：

claude mcp add calendar -- npx -y @theluckystrike/mcp-calendar

（.cursor/mcp.json）：

{
  "mcpServers": {
    "calendar": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-calendar"]
    }
  }
}

上面的 npx 方式会在软件包发布后立即生效。在此之前，请使用上面的 .mcpb 安装包，或严格按以下四条命令从源代码构建：

git clone https://github.com/theluckystrike/mcp-servers.git && cd mcp-servers
npm install
npm run build -w packages/mcp-license -w servers/timezone -w servers/calendar

然后将客户端的 command 指向 node，并传入一个参数：servers/calendar/dist/index.js 的绝对路径。

要以 Pro 模式运行，请在同一配置块中设置 MCP_LICENSE_KEY，或使用你的密钥调用一次 license_activate。

从日历中导出 .ics 文件

应用	位置
Google Calendar	Settings -> Import & export -> Export。你会得到一个 zip 文件；导入其中的 .ics 文件。
Apple Calendar	File -> Export -> Export...
Outlook（桌面版）	File -> Save Calendar，格式选择 iCalendar (.ics)
Outlook / Microsoft 365（网页版）	Settings -> Calendar -> Shared calendars -> Publish，然后使用 ICS 链接（Pro）
其他应用	任何以 .ics 结尾的已发布订阅源 URL，或 webcal://（Pro）

然后：ics_import {path: "~/Downloads/[email protected]", name: "work"}

工具

工具	功能
ics_import	读取 .ics 文件（path）、粘贴的内容（text）或公开订阅源（url，Pro），并以指定名称保存在本地。再次导入同名日历会替换原日历。
calendars_list	列出所有已导入的日历：名称、来源、事件数量、大小和导入时间。
events_list	列出两个日期之间的所有事件，将重复系列展开为实际发生的事件，按时间排序，并使用你自己的时区。每一行都包含一个 ID。
events_search	搜索标题、描述、地点、组织者或参与者中包含指定短语的事件。
free_busy	按天合并显示忙碌时段，以及工作时间内的空闲时段。标记为“空闲/透明”的事件不计为忙碌。
conflicts	列出所有重叠的事件对及重叠分钟数，并检查所有日历，因此与客户通话和接送孩子时间冲突的情况也能被发现。较长的时间范围会缩短至可查询的 31 天，并返回结果，不会拒绝请求。
next_event	显示下一项尚未开始的日程，以及距离开始还有多久。
event_export	将选定的事件（按 ID 指定，或指定整个时间范围）写入新的 .ics 文件，供你发送。时间使用 UTC，因此在任何客户端上都能正确显示。
event_to_time_entry	将一次会议转换为时间追踪器 entry_add 所需的准确参数，无需重新输入即可将通话记录为可计费时间。
ics_forget	移除一个日历及其本地副本。
license_status / license_activate	查看许可证等级；离线激活 Pro 密钥。

资源 calendar://today 一次即可提供今天的日程。提示词 plan_my_day 会引导你完成整个流程：查看日程、检查冲突、查找空闲时段，以及确定哪些已结束的会议需要计费。

解析器支持的内容

解析器依据真实导出文件编写，而不仅仅是规范：折叠行（CRLF、裸 LF 和裸 CR，以及 Exchange 在多字节字符中间折叠的行；这类行会先按字节重新拼接，再解码）、\n \, \; \\ 转义、结束时间为排他值 DTEND 的全天事件、用 DURATION 代替 DTEND、TZID 和 UTC 时间、浮动时间、RRULE 中的 HOURLY、DAILY、WEEKLY、MONTHLY 和 YEARLY，以及 COUNT、UNTIL（含边界）、INTERVAL、BYDAY（包括序数，如 2MO、-1FR）、BYMONTHDAY、BYMONTH 和 BYSETPOS、EXDATE、RDATE、RECURRENCE-ID 覆盖项（移动后的实例会替代原实例，而不是重复显示）、STATUS:CANCELLED、TRANSP:TRANSPARENT，以及事件内的 VALARM 块。无法读取的事件会被跳过并计数，不会因此丢弃文件中的其余内容。

我们有意不展开 FREQ=MINUTELY 和 FREQ=SECONDLY：这类规则会让任意时间范围内都充满数千个事件，掩盖一周内的其他日程。这些事件会列在首次发生时间处，并明确说明原因。没有 COUNT 和 UNTIL 的规则只会展开到你请求的时间范围。

此服务写出的导出文件会将全天事件保留为 DATE 值，因此节假日会保持原来的日期，不会因设备时区而变成前一天的定时事件。

我们有意忽略 VTIMEZONE。文件内嵌的 DST 规则是否最新，取决于生成文件的应用；我们会保留 TZID，并改用 Node 构建中的 ICU 数据计算所有时区偏移。这样可以确保每周在华沙当地时间 10:00 举行的会议，在 3 月时钟调整后仍保持当地时间 10:00。

免费版与 Pro 版

	免费版	Pro（一次性支付 $19）
保留的日历数量	2	无限
每次查询的时间范围	最长 31 天	任意范围
超过较长时间范围的 conflicts	返回前 31 天的结果，并注明上限	任意范围
每次导出的事件数量	50	无限
从 URL 或 webcal 订阅源导入	--	支持
其他所有功能	完整	完整

获取 Pro，也可支付 $39 一次性购买套件中的所有服务，终身使用。

隐私

所有内容都在本地处理。导入的日历文件会复制到 ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/calendar/，并从该目录读取；删除该目录即可重置服务。 整个服务中只有一次网络调用，且仅在你自行传入 url 时发生：服务会获取该地址一次，超时时间为 12 秒，文件大小上限为 5 MB，并拒绝访问回环、私有和云元数据地址。不会上传任何内容，不会关联任何账户，许可证密钥也会离线验证。

搭配使用

• mcp-timezone，本服务会从中读取时区和 .ics 引擎：转换会议时间、查找跨国家/地区的空档、编写邀请。
• mcp-time-tracker，event_to_time_entry 会将已完成的会议交给它；它会跟踪并报告时长。
• mcp-invoice，将跟踪的时长转换为带编号的发票。
• office-suite，一次安装即可使用多个服务，只需一项配置。

常见问题

不会。没有 OAuth、没有令牌，也不会同步。你可以导出文件（或在 Pro 版中粘贴公开订阅源 URL），然后在本地读取。这也意味着导入的内容是一个快照：日历有更新后，请重新导入。

是的，这也是大部分代码所处理的内容。每周重复的系列会按墙上时钟时间展开，因此华沙时间 10:00 的会议在夏令时切换后仍是 10:00，而不会漂移到 11:00。每月 31 日的事件在 2 月会跳过，而不会顺延到 3 月；UNTIL 会包含恰好落在该日期的事件；单个已移动的实例会替换原事件。

不会：RFC 5545 规定，全天事件的 DTEND 是排他的，因此 6 月 1 日至 3 日表示 1 日和 2 日。本服务遵循该规范，你的日历应用也是如此。

它会通过 event_export 写入 .ics 文件，你可以在任何地方导入这些文件。它绝不会修改读取过的日历。

5 MB，可容纳数千个事件。如果完整历史记录超过此大小，请导出较窄的日期范围。

将这些文档用作 MCP 服务

任何 MCP 客户端（Claude、Cursor、Windsurf、VS Code）都可以通过 GitMCP 直接读取此代码库的文档，无需安装：

• Docs MCP URL：https://gitmcp.io/theluckystrike/mcp-calendar