when-free

when-free

有人问你什么时候有空。它会读取你的日历，并给出答案，让你可以直接粘贴。

• 粘贴消息，获取空闲时段。 它能读懂“下周二或周三，上午 10 点到下午 4 点”，并针对指定日期和时段给出答案。
• 支持 Google、Outlook 和 iCloud 日历，也支持任何 .ics 文件。还可以同时使用多个日历。
• 保护隐私。 它在你的电脑上运行，无需账号或 API 密钥，也不会修改你的日历。
• 也能通过 AI 工具使用： Claude、Cursor 和其他 MCP 客户端、Open WebUI、n8n、Shortcuts、脚本。
• 也能在其他设备上使用： 手机、平板和手表、Home Assistant（以及通过它使用 Alexa、Google Home、Siri），还有 macOS、Linux 和 Windows 的菜单栏或状态栏。

目录

立即试用 · 添加日历 · 日常使用 · 解析消息 · 通过其他工具使用 · 其他设备 · 隐私 · 设置 · 忙碌时段的判定方式 · 限制 · 问题排查 · 收录位置

一分钟内试用

使用 uv，无需预先安装：

uvx when-free demo

要保留它（需要 Python 3.11 或更高版本）：

uv tool install when-free          # or: pipx install when-free
whenfree demo

在使用 Claude Desktop？可以跳过以上步骤：安装一键扩展。

whenfree demo 会生成下周的模拟日历，并据此回答招聘人员的消息。它不会读取你的任何数据，也不会保存任何内容：

  > Hi! Thanks for applying. Could you share a few times on Tuesday, Wednesday or Thursday next week,
  > between 10am and 4pm? The interview takes about an hour.

  Free between 10:00 and 16:00 (Europe/London), slots of 60+ minutes, 15-minute buffer around events:
  - Tue 13 Oct: 11:45–12:45, 14:15–16:00
  - Wed 14 Oct: 12:15–14:15
  - Thu 15 Oct: 13:15–14:45

添加日历

1. 复制日历的私有地址。 这是一个以 .ics 结尾的链接：

   日历	查找位置
   Google Calendar	设置 → 点击左侧的日历 → 集成日历 → iCal 格式的私有地址
   Outlook	设置 → 日历 → 共享日历 → 发布日历 → ICS 链接
   iCloud	日历 → 点击日历旁的共享图标 → 公开日历（webcal:// 链接也可以）
   其他	任意 .ics 链接，或导出的 .ics 文件

2. 运行 whenfree add 并粘贴地址。 粘贴时不会显示该地址。系统会先检查，只有可用时才会保存：

   $ whenfree add
   Paste the address and press Enter (it is not shown):
   Added 'personal': 412 events, 9 block time in the next 14 days.
   Saved in /Users/you/.config/when-free/config.toml, readable only by you. Now run: whenfree
   

3. 运行 whenfree。 你会看到接下来几个工作日的空闲时间。

在 Mac 上，pbpaste | whenfree add 可以直接从剪贴板读取地址。

请保密该地址。 它就像密码：任何拥有它的人都能读取该日历。只将它提供给 whenfree add，不要用于其他任何地方，例如聊天、Shell 命令或代码仓库。如果地址泄露，请在日历设置中重置。

whenfree add --name work                 # a second calendar: asks for its address
whenfree add ~/calendars/family.ics      # an exported file instead of an address
whenfree check                           # can every calendar be read?

日常使用

只有时段行会输出到标准输出。上下文信息会输出到标准错误，因此使用 | pbcopy 时，复制的内容正好可以粘贴到回复中。

阅读消息

--message 可以从普通文本中找出日期和时间。它能理解：

• 各种常见写法的日期： Thu 1 Oct · Thursday the 1st of October · Monday, October 5th · 5 October · 2026-10-05 · Wednesday 30th
• 时间： between 10:00am and 4:00pm · 10:00–16:00 · 9-5pm · 2 to 4 pm
• 未给出日期时使用的词语（这里假设今天是 10 月 1 日星期四）：

它总会告诉你如何解读日期，方便你对照消息进行核查。以下规则可以避免它猜测：

• 明确写出的日期优先。 如果“Next week:”这样的标题下方写着“Wednesday 30th, Thursday 1st”，不会因此再加上整整一周。
• **“Good morning”是问候语，**不是时间。
• **已经过去的日期会被排除并注明，**绝不会悄悄忽略。“Wednesday 30th”指最近的一个日期为 30 日的星期三，因此，来自上周的消息会被解读为上周。
• 相对日期以今天为准。 对于较早的消息，如果其中写着“tomorrow”，请使用 --days 手动提供日期。

when-free 不会连接你的邮箱。你可以粘贴消息、通过管道传入消息，或将消息保存到文件中。

[extract]
command = ["ollama", "run", "llama3.2"]          # the prompt is sent on standard input
# command = ["my-cli", "ask", "{prompt}"]        # or placed where {prompt} is

在其他工具中使用

所有方式都会给出相同的答案，只进行读取，并且除非另有要求，否则不会包含事件标题。

Claude Code 插件

该插件将 MCP 服务与一项技能打包在一起，用来告诉 Claude 何时使用它：当你询问自己的空闲时间、粘贴询问何时可以见面的消息，或在它提出时间之前。

/plugin marketplace add YauhenBichel/when-free
/plugin install when-free@when-free

然后添加一次日历（如果你尚未添加）：uvx when-free add

MCP：Claude、Cursor 和其他助手

claude mcp add when-free -- uvx when-free mcp          # Claude Code

对于 Cursor 和其他 MCP 客户端，将以下内容添加到其服务列表中。uvx 首次运行时会自动获取 when-free，因此无需安装：

{
  "mcpServers": {
    "when-free": { "command": "uvx", "args": ["when-free", "mcp"] }
  }
}

如果你使用 uv tool install 安装，请改用 "command": "whenfree", "args": ["mcp"]。它也已列入 MCP registry，标识为 io.github.YauhenBichel/when-free，并收录于 mcprush 和 M8ven Trust Index。

然后只需询问：“这是招聘人员发来的消息。我能参加其中哪些时间？”助手会调用 free_slots，并根据你的实际日历作答。

如果工具无法完成任务，助手会收到可读的错误信息（“无法读取日历 ‘work’”），绝不会猜测。

HTTP：Open WebUI、n8n、Shortcuts 和脚本

whenfree serve                    # http://127.0.0.1:8765, only reachable from this computer

curl -H "Authorization: Bearer $(cat ~/.config/when-free/token)" \
  'http://127.0.0.1:8765/free_slots?days=next%20week&hours=afternoon'

• 使用 JSON 请求体向 /free_slots 发送 POST 请求，或使用带查询字符串的 GET 请求。/check_calendars 也相同。
• 返回内容为 {"ok": true, "text": "...", "data": {...}}，或状态码为 400 的 {"ok": false, "error": "..."}。
• /openapi.json 提供 OpenAPI 描述。要设置 Open WebUI、n8n 或 Shortcuts，请参阅配置指南。
• 令牌会在首次运行时创建，并保存在 ~/.config/when-free/token 中，只有你能读取。也可以通过 WHENFREE_TOKEN 设置自己的令牌。每次工具调用都需要令牌。
• 发往此计算机以外任何主机的请求都会被拒绝。网页只能从你允许的来源调用它：whenfree serve --allow-origin http://localhost:3000。使用 --host 0.0.0.0 时，网络中的其他设备也可以访问；此时只有令牌提供保护，因此仅在你信任的网络中使用。

函数调用执行环境

whenfree schema                    # the tool definitions: name, description, inputSchema
whenfree schema --format openai    # the same, as {"type": "function", "function": {...}}
whenfree call free_slots --args '{"days": "next week", "hours": "10:00-16:00"}'

whenfree call 会输出 {"ok": true, "text": "...", "data": {...}}，或 {"ok": false, "error": "..."}，并以退出代码 1 结束。参数也可以通过标准输入传入。

Python

from whenfree import api

result = api.find_free(api.Query(days="next week", hours="10:00-16:00", min_minutes=45))
for day in result["days"]:
    print(day["label"], day["free"])          # for example: Mon 12 Oct [['10:00', '11:45'], ['13:15', '16:00']]

find_free 返回普通的字典和列表，可直接用于 json.dumps；遇到问题时会抛出 api.Problem，其中的消息可安全显示。传入 reader= 可自行提供日历文本，而不从日历中获取。

在你的其他设备上

$ whenfree now
Busy until 15:30 · next free 15:45–17:00

设备可以查看你是否有空以及你的空闲时段，但看不到事件标题。每部手机都有独立的令牌，你可以撤销令牌；无法读取的日历会显示为“未知”，绝不会显示为“空闲”。

隐私

• 它在你的电脑上运行。 它只会获取你的日历订阅源，不会获取其他内容。它从不写入日历，也从不发送消息。
• 你的日历地址会保密。 地址不会被打印出来，你粘贴时也不会显示，而且会存储在只有你能读取的文件中。错误信息会指出日历名称（“个人”），而不会显示其地址。
• 助手只能看到空闲时间，看不到你的事件。 除非助手使用 include_busy 请求，否则不会包含事件标题；该选项的说明也会告知模型标题属于隐私信息。没有任何工具可以添加、更改或删除内容，也没有工具会接收日历地址；日历地址只会从你这里传给 whenfree add。

设置

除日历外，所有设置都是可选的。设置存放在 ~/.config/when-free/config.toml 中，命令行标志的优先级高于文件中的设置。

什么情况算作忙碌

经过缓冲时间后，短于 min_minutes 的时段不会被提供。对于今天，计算从下一个 15 分钟刻度开始，而不是从过去的时间开始。

限制

• 它只读取，不会预约。 它绝不会写入日历或发送消息。
• 数据新鲜度取决于日历源。 Google 刷新私密地址需要一些时间，因此刚刚添加的事件可能不会显示。运行 whenfree --busy 查看它读取到的内容。
• 要么读取所有日历，要么一个也不显示。 如果有一个日历无法读取，就不会显示任何时段，因为忙碌时间可能会被误认为空闲。
• 重复事件。 支持展开每日、每周、每月（按日期或“第一个星期一”“最后一个星期五”）和每年的规则，以及间隔、结束日期、次数、跳过的日期和已移动的实例。不支持较少见的规则（BYSETPOS、周数）。对于这些规则，首个日期会被标记为占用，并附有说明。
• 时区取自事件。如果时区数据库不认识某个时区名称（某些 Outlook 导出会出现这种情况），则会按你所在的时区读取。

如果遇到问题

收录位置

• 官方 MCP 注册表，名称为 io.github.YauhenBichel/when-free
• PyPI，名称为 when-free
• Glama、MCP Servers Live 和 MCP Changefeed，这些平台会收录 MCP 服务

如果你在某处使用了它，或撰文介绍了它，请提交 issue，相关内容就会收录在这里。

开发

uv run --with pytest pytest -q        # a few seconds; no network

测试使用 tests/data/sample.ics 中的小型日历和固定时钟（WHENFREE_NOW）。代码按组件分组：

如果某个组件导入了不允许使用的组件，tests/test_structure.py 就会报错，从而确保领域代码不依赖任何前端。

请参阅 CONTRIBUTING.md。

许可证

Apache-2.0。