lilt-mcp
# lilt-mcp
## What it is
`lilt-mcp` is an MCP server that lets Claude read and manage your tasks and habits in [Lilt](https://apps.apple.com/us/app/lilt-tasks-habits-tracker/id6768083170), a task and habit tracker for macOS. It works with Claude Desktop, Claude Code, and any other MCP client that can launch a stdio server.
## Requirements
- macOS
- Node.js 18 or later (not needed for the Claude Desktop `.mcpb` bundle, which uses the app's own runtime)
- Lilt 1.1 or later from the Mac App Store, launched at least once
- iCloud Drive turned on if you use Claude Desktop (see [How it works](#how-it-works))
## Install for Claude Desktop
1. Download `lilt-mcp.mcpb` from the [latest GitHub release](https://github.com/saibuddha-personal/lilt-mcp/releases/latest).
2. Double-click the file, or drag it into Claude > Settings > Extensions.
## Install for Claude Code
```bash
claude mcp add lilt -- npx -y lilt-mcp
```
## Manual config for other MCP clients
```json
{
"mcpServers": {
"lilt": {
"command": "npx",
"args": ["-y", "lilt-mcp"]
}
}
}
```
If your client can't find `npx`, use the absolute path from `which npx` as the `command`.
## Tools
| Tool | What it does |
|---|---|
| `list_tasks` | Open tasks by default; filter by `status`, `project`, `due_within_days`, `overdue_only`; snoozed tasks hidden unless `includeSnoozed`. Returns `[id]` prefixes. |
| `list_projects` | Projects with open-task counts. Use these exact names for `project`. |
| `list_habits` | Habits with today's progress, streak, and a 7-day strip. |
| `create_task` | title, notes, priority, due, project, plus recurrence (`recurrence`, `interval`, `weekdays`, `monthly_anchor`) and `show_days_before`. |
| `complete_task` | Mark done. Repeating tasks spawn their next occurrence. |
| `reopen_task` | Done → To Do. |
| `snooze_task` | Hide an open task until a wake time: `preset` (`end-of-day`, `1-day`, `2-days`, `3-days`, `1-week`) or `until` (ISO-8601). |
| `unsnooze_task` | Clear a snooze; the task reappears immediately. |
| `update_task` | Partial edit of any field; `status: done` behaves like complete. |
| `delete_task` | Permanent. For repeating tasks, `scope: occurrence` (default, series continues) or `series` (ends it). |
| `log_habit` | Log today, or backfill with `date`. Omit `count` to add one; set `count` for an exact total (0 clears). |
**Identifying a task:** every mutating tool accepts either `id` (full UUID or a unique prefix like `a1b2c3d4`) or `title` (exact, case-insensitive; falls back to a unique partial match). Ambiguous matches return the candidates instead of guessing. Habits use `id` or `name`.
## How it works
```
Claude ──▶ lilt-mcp ──▶ snapshot.json (READ)
└──▶ open -g "lilt://complete-task?…" (WRITE) ──▶ Lilt
└──▶ re-reads snapshot to confirm the change landed
```
- **Read:** Lilt writes `snapshot.json` (tasks, projects, habits, with ids) after every change. The `list_*` tools read it. The server tries these paths in order:
1. `$LILT_SNAPSHOT_PATH`, if set
2. `~/Library/Containers/saibuddha.Flow/Data/Library/Application Support/Lilt/snapshot.json`
3. `~/Library/Application Support/Lilt/snapshot.json`
4. `~/Library/Mobile Documents/iCloud~saibuddha~Flow/Documents/snapshot.json`
Some MCP hosts (such as Claude Desktop) are sandboxed and can't read Lilt's app container, but can read the iCloud Drive copy in path 4. That requires iCloud Drive to be on.
- **Write:** each mutating tool fires a `lilt://` URL with `open -g` (Lilt stays in the background), then polls the snapshot so the result reports what actually happened.
- **Versions:** the snapshot carries a schema `version`. If Lilt and lilt-mcp disagree, tool results start with a one-line note telling you which to update.
## Troubleshooting
- **"Lilt doesn't seem to be installed or hasn't been launched yet."** No snapshot exists at any known path. Install Lilt from the Mac App Store, open it once, then try again.
- **"This MCP host can't read Lilt's app container, and Lilt's iCloud Drive copy isn't present."** Your MCP host is sandboxed. Turn on iCloud Drive in System Settings > Apple Account > iCloud, make sure Lilt is running (Lilt 1.1 or later), then try again.
- **"Lilt's snapshot file is corrupted or mid-write; try again in a moment."** Lilt was writing the file as it was read. Retry. If it persists, quit and relaunch Lilt.
- **"couldn't confirm" after a write:** the URL was sent but the snapshot didn't change within 2.5 seconds. Lilt may have been asleep or just launching; run `list_tasks` to check.
- **`node: command not found`** in your client's logs: use the absolute path from `which node` (or `which npx`) as the `command`.
If none of these match, the error lists every path tried and the error code for each. You can point the server at a specific file with `LILT_SNAPSHOT_PATH`.
## Development
```bash
npm install
node index.js --help
npm run pack:mcpb # builds dist/lilt-mcp.mcpb
```
## Releasing
1. Bump `version` in both `package.json` and `manifest.json` (the pack script refuses to run if they differ).
2. Commit and tag: `git tag v1.1.0 && git push --tags`.
3. `npm publish`.
4. Run `npm run pack:mcpb` and attach `dist/lilt-mcp.mcpb` to the GitHub release.
## License
MIT
TDQS
Scored across 11 tools
Most tools map cleanly to a distinct resource+action (create/update/delete/complete/reopen/snooze/unsnooze on tasks, list/log on habits, list on projects). The only mild friction is that update_task's allowed fields are unspecified, so an agent might wonder whether status changes belong there rather than in complete_task/reopen_task. Snooze/unsnooze are explicitly delineated as out-of-band from update_task, which keeps the boundaries largely clear.
Every tool follows the same snake_case verb_noun pattern (list_projects, create_task, log_habit, unsnooze_task). Verb choice is also semantically consistent, with paired opposites (snooze/unsnooze, complete/reopen) named symmetrically.
Eleven tools is well within a comfortable range for a task/habit client. Each tool covers a genuinely distinct operation — the task lifecycle alone justifies seven of them, and no tool looks redundant or vestigial.
The task surface is essentially complete (create, list, update, delete, complete, reopen, snooze, unsnooze). However, habits only have list and log — there is no way to create, edit, or archive a habit — and projects are read-only, so agents will hit dead ends outside the task domain. Workarounds exist (habits/projects presumably managed in the Lilt app), but the surface is uneven.