kenotex-mcp

kenotex-mcp

Let your coding agent manage your real todos, calendar, and habits.

Kenotex is a native planner for Mac and iPhone. This package is its MCP server: point Claude Code, Claude Desktop, Cursor, Zed, or any MCP client at it, and the agent works on the actual items in the app — creating todos with categories and recurrence, scheduling calendar events, ticking off daily or interval check-in habits. Not a scratchpad, not a markdown file. Everything lives in a local SQLite database on your own machine.

Your agent writes on your Mac. It's on your iPhone via iCloud.

Works with Claude Code, Claude Desktop, Cursor, Zed, OpenClaw, and anything else that speaks MCP over stdio.

Get the app

These tools drive the Kenotex macOS app — it hosts the local server this package talks to, so you need it installed and running. Free to download, with in-app purchases.

The MCP integration is not one of those purchases. Every tool in this package talks to the app's local HTTP server, which has no subscription gate — the whole integration works on the free tier.

→ kenxcomp.com/kenotex

Prerequisites

• macOS 26 or later — the app's minimum. The iPhone app syncs over iCloud, but the MCP server talks to the Mac.
• The Kenotex macOS app must be running (it hosts the local HTTP server on port 21519).
• Node.js 20+ or Bun.

Install

Globally:

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

Or use it directly via npx / bunx (no install):

npx kenotex-mcp

Configure in an MCP client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop. You'll see the Kenotex tools appear in the 🛠️ menu.

Cursor / Zed / OpenClaw

Same pattern: point the MCP config at kenotex-mcp as the command.

Environment overrides

• KENOTEX_HOST — override base URL (default http://127.0.0.1:21519).
• KENOTEX_TOKEN — skip filesystem token discovery and use this token.

Tools exposed

Category	Tool
Todo	create_todo list_todos get_todo update_todo complete_todo delete_todo
Event	create_event list_events get_event update_event delete_event
Habit	create_habit list_habits get_habit update_habit set_habit_check list_habit_checks delete_habit
Category	list_categories create_category
Reminder	add_reminder remove_reminder

create_todo requires a categoryId — todos can no longer be created uncategorized. The flow is: call list_categories and reuse a matching category's id; if none fits, call create_category and use the returned id, then create_todo.

Habits are check-in trackers (medication, water, stretching) — daily by default (up to 6 dose times/day), or interval (Q times every N days / N times a week / N times a month) via cadence. Use create_habit for routines the user ticks off; use create_todo + recurrence for one-off tasks or fixed-slot schedules (a particular weekday, a particular day of the month) — cadence counts how many times per period, recurrence pins which day. Writes take times: ["HH:mm", …]; reads return times: [{id, time}] — pass a slot's id as slotId to set_habit_check for a multi-dose habit (omit it to check all of today's doses). cadence: {"unit":"day"|"week"|"month","interval":N,"quota"?:Q,"startDate"?:"yyyy-MM-dd"} makes an interval habit — quota defaults to 1, out-of-range is a 422 and is never clamped, startDate defaults to today and can never be changed afterwards, and an interval habit takes at most one dose time:

unit	interval	quota	period
day	1–365	1–interval	N calendar days, so quota ≤ N; day/1 takes quota 1 = explicitly daily
week	1–8	1–7×interval	N week(s)
month	1–12	1–min(31×interval, 365)	N whole calendar months (1st → last day), so the due day is always month end and the period's length follows the calendar rather than a fixed 30 days

Examples: {"unit":"day","interval":3} = every 3 days · {"unit":"day","interval":5,"quota":2} = twice every 5 days · {"unit":"week","interval":1,"quota":2} = twice a week · {"unit":"month","interval":1,"quota":2} = twice a month.

Reads add cadence, isIntervalHabit and currentPeriod {start,end,dueDay,doneCount,quota,done} (quota is the period's effective quota — the configured quota clamped to the period's checkable days from startDate on, so a 31-a-month habit reports 28 in February and 17 for a first month started on the 14th) — use currentPeriod.done for "is this period satisfied" (checkedToday stays a calendar-day fact). update_habit {"cadence": null} turns an interval habit back into a daily one (anchor kept). Interval habits are checked per calendar day (no slotId; date never in the future). Checking is explicit set-state (checked: true|false, date defaults to today, idempotent, false un-checks). delete_habit permanently deletes the habit and its entire check-in history — set an endDate via update_habit to stop-but-keep-records instead.

App version: habit tools require the Kenotex app release that ships /v1/habits (1.2.9+, local API v2). cadence additionally requires the release that advertises local API v3 — against an older app a cadence write is refused up front with VERSION_SKEW rather than being silently ignored, and once the app is updated you just retry (the check re-reads the running app's version, no MCP restart needed). Nothing else is gated: on a v2 app every other tool, habit tools included, behaves exactly as it did before — only cadence is unavailable.

Recurrence DSL: 'daily' / 'weekly:mon,wed,fri' / 'monthly:15' / 'yearly' / 'after:daily' (todos only) / 'none'.

Virtual event occurrences: get_event accepts ids like {parentId}__occ__{yyyy-MM-dd}. Recurring parents materialize past occurrences on delete.

How auth works

On each HTTP request the server reads the Kenotex bearer token from (in order):

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

The token is rotated each time the Kenotex app starts, so a stale MCP session just re-reads the file on its next tool call.

Troubleshooting

"Kenotex app not running or token not accessible" — launch Kenotex.app. If running, the token file should exist at one of the three paths above.

Requests time out — check that no firewall is blocking localhost:21519; tools are hardcoded to 10-second timeout.

License

MIT © kenxcomp