Skip to main content
Glama

lilt-mcp

What it is

lilt-mcp is an MCP server that lets Claude read and manage your tasks and habits in Lilt, 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.

Related MCP server: Things 3 MCP 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)

Install for Claude Desktop

  1. Download lilt-mcp.mcpb from the latest GitHub release.

  2. Double-click the file, or drag it into Claude > Settings > Extensions.

Install for Claude Code

claude mcp add lilt -- npx -y lilt-mcp

Manual config for other MCP clients

{
  "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

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

Available Tools

11 tools
complete_taskA

Mark a task done in Lilt. Identify it by id or title. If the task repeats, the next occurrence is created automatically.

Inputs: id, title.

create_taskB

Create a new task in Lilt. It lands in 'To Do' and syncs to all the user's devices via iCloud.

Inputs: title (required), due, notes, project, +6 more.

delete_taskA

Delete a task in Lilt (permanent). Identify it by id or title. For a repeating task, scope controls whether only this occurrence is removed (series continues with the next one) or the whole series ends.

Inputs: id, scope, title.

list_habitsA

List the user's habits in Lilt with today's progress, streaks, and the last 7 days. Use the [id] with log_habit.

Inputs: no named parameters.

list_projectsA

List the user's projects in Lilt with open-task counts. Use these exact names for the project parameter elsewhere.

Inputs: no named parameters.

list_tasksA

List the user's tasks in Lilt with their ids. By default shows open tasks only (To Do + In Progress). Use the returned [id] prefix with complete_task / update_task / delete_task.

Inputs: limit, status, project, overdue_only, +2 more.

log_habitA

Log a habit completion in Lilt — today by default, or a past date to backfill. Identify the habit by id or name. Omit count to add one completion; pass count to set that day's total exactly (0 clears it).

Inputs: id, date, name, count.

reopen_taskA

Move a completed task back to 'To Do'. Identify it by id or title (searches done tasks too).

Inputs: id, title.

snooze_taskA

Snooze an open task: hide it from Lilt's board, menu bar and list_tasks until a wake time. Status, due date, project and recurrence are unchanged. Pass exactly one of preset or until.

Inputs: id, title, until, preset.

unsnooze_taskA

Clear a task's snooze so it reappears in Lilt immediately. Identify it by id or title.

Inputs: id, title.

update_taskA

Edit a task in Lilt. Only the fields you pass are changed. Identify the task by id or title. Pass an empty string for due or project to clear them; pass recurrence 'none' to stop repeating.

Inputs: id, due, notes, title, +9 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers