kenotex-mcp

kenotex-mcp

让你的编码 Agent 管理真实的待办事项、日历和习惯。

Kenotex 是一款适用于 Mac 和 iPhone 的原生规划应用。 此软件包是它的 MCP 服务：让 Claude Code、Claude Desktop、Cursor、Zed 或任何 MCP 客户端连接到它，Agent 就能操作应用中的实际项目——创建带有类别和重复规则的待办事项、 安排日历事件，以及勾选每日或按间隔打卡的习惯。 不是草稿本，也不是 Markdown 文件。所有内容都保存在你自己设备上的本地 SQLite 数据库中。

你的 Agent 在 Mac 上写入内容。通过 iCloud 同步到你的 iPhone。

适用于 Claude Code、Claude Desktop、Cursor、Zed、OpenClaw，以及 任何其他通过 stdio 使用 MCP 的工具。

获取应用

这些工具由 Kenotex macOS 应用驱动——它会托管此软件包连接的本地服务，因此你需要安装并运行该应用。可免费下载，并提供应用内购买。

MCP 集成不属于付费项目。 此软件包中的所有工具都会与应用的本地 HTTP 服务通信，该服务没有订阅限制——整个集成都可以在免费版中使用。

→ kenxcomp.com/kenotex

前置条件

• macOS 26 或更高版本——这是应用的最低系统要求。iPhone 应用通过 iCloud 同步，但 MCP 服务连接的是 Mac。
• Kenotex macOS 应用必须处于运行中（它会在端口 21519 上托管本地 HTTP 服务）。
• Node.js 20+ 或 Bun。

安装

全局安装：

npm install -g kenotex-mcp
# or
bun add -g kenotex-mcp

也可以通过 npx / bunx 直接使用（无需安装）：

npx kenotex-mcp

在 MCP 客户端中配置

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "kenotex": {
      "command": "npx",
      "args": ["-y", "kenotex-mcp"]
    }
  }
}

重启 Claude Desktop。你会在 🛠️ 菜单中看到 Kenotex 工具。

Cursor / Zed / OpenClaw

同样的方式：在 MCP 配置中将 kenotex-mcp 指定为 command。

环境变量覆盖

• KENOTEX_HOST — 覆盖基础 URL（默认值为 http://127.0.0.1:21519）。
• KENOTEX_TOKEN — 跳过文件系统中的令牌发现，改用此令牌。

提供的工具

类别	工具
待办事项	create_todo list_todos get_todo update_todo complete_todo delete_todo
事件	create_event list_events get_event update_event delete_event
习惯	create_habit list_habits get_habit update_habit set_habit_check list_habit_checks delete_habit
类别	list_categories create_category
提醒事项	add_reminder remove_reminder

create_todo 需要 categoryId——待办事项必须指定类别。操作流程：调用 list_categories 并复用匹配类别的 id；如果没有合适的类别，则调用 create_category 并使用返回的 id，然后调用 create_todo。

习惯是打卡追踪项（如服药、喝水、拉伸）——默认为每日（每天最多 6 个服用时间），也可以通过 cadence 设置为按间隔（每 N 天 / 每周 / 每月 Q 次）。使用 create_habit 创建由用户打卡的日常事项；对于一次性任务或固定时段安排（指定某个星期几、指定某个月中的某一天），请使用 create_todo + 重复规则——cadence 用于计算每个周期内的次数，重复规则则指定具体日期。写入时使用 times: ["HH:mm", …]；读取时返回 times: [{id, time}]——对于多次服用的习惯，将某个时段的 id 作为 slotId 传给 set_habit_check（省略它则勾选今天的所有时段）。cadence: {"unit":"day"|"week"|"month","interval":N,"quota"?:Q,"startDate"?:"yyyy-MM-dd"} 可创建按间隔打卡的习惯——quota 默认为 1，超出范围时会返回 422，且不会自动限制到允许范围内；startDate 默认为今天，之后无法更改；按间隔打卡的习惯最多只能设置一个服用时间：

unit	interval	quota	周期
day	1–365	1–interval	N 个日历日，因此 quota ≤ N；day/1 的 quota 为 1，即明确表示每天
week	1–8	1–7×interval	N 周
month	1–12	1–min(31×interval, 365)	N 个完整的日历月（从 1 日到最后一天），因此到期日始终是月末，周期长度随日历变化，而非固定为 30 天

示例：{"unit":"day","interval":3} = 每 3 天一次 · {"unit":"day","interval":5,"quota":2} = 每 5 天两次 · {"unit":"week","interval":1,"quota":2} = 每周两次 · {"unit":"month","interval":1,"quota":2} = 每月两次。

读取结果会添加 cadence、isIntervalHabit 和 currentPeriod {start,end,dueDay,doneCount,quota,done}（quota 是周期的实际配额——配置的配额会限制为从 startDate 起可打卡的天数，因此每月 31 次的习惯在 2 月会报告 28 次，在 14 日开始的第一个月会报告 17 次）——判断“本周期是否已完成”请使用 currentPeriod.done（checkedToday 仍表示日历日事实）。update_habit {"cadence": null} 会将间隔习惯恢复为每日习惯（保留锚点）。间隔习惯按日历日打卡（没有 slotId；date 不能是未来日期）。打卡采用明确的设置状态（checked: true|false，date 默认为今天，具有幂等性，false 表示取消打卡）。delete_habit 会永久删除习惯及其全部打卡历史——如需停止习惯但保留记录，请通过 update_habit 设置 endDate。

应用版本：习惯工具需要包含 /v1/habits 的 Kenotex 应用版本（1.2.9+，本地 API v2）。cadence 还需要声明本地 API v3 的应用版本——在较旧的应用上，cadence 写入会在执行前被拒绝，并返回 VERSION_SKEW，而不会被静默忽略；应用更新后只需重试即可（检查会重新读取运行中应用的版本，无需重启 MCP）。其他功能均不受限制：在 v2 应用上，其他所有工具（包括习惯工具）的行为与之前完全一致，只有 cadence 不可用。

重复规则 DSL：'daily' / 'weekly:mon,wed,fri' / 'monthly:15' / 'yearly' / 'after:daily'（仅限 todos）/ 'none'。

虚拟事件实例：get_event 接受格式为 {parentId}__occ__{yyyy-MM-dd} 的 ID。删除重复事件的父项时，会将过去的实例转换为实际事件。

身份验证的工作方式

每次 HTTP 请求时，服务都会按以下顺序读取 Kenotex bearer 令牌：

1. ~/Library/Containers/com.kenxcomp.kenotex/Data/Library/Application Support/Kenotex/local-http-token
2. ~/Library/Application Support/Kenotex/local-http-token
3. ~/.kenotex-local-token

每次 Kenotex 应用启动时都会轮换令牌，因此过期的 MCP 会话会在下次调用工具时重新读取文件。

故障排除

“Kenotex app not running or token not accessible”——启动 Kenotex.app。如果应用正在运行，令牌文件应位于上述三个路径之一。

请求超时——检查是否有防火墙阻止 localhost:21519；工具的超时时间硬编码为 10 秒。

许可证

MIT © kenxcomp