things3-mcp-server

MCP server for Things 3 on macOS. Read and write to-dos, lists, areas and projects — so an agent can drive the same task workflows a human does in Things (triage Today, log completed work, file new tasks, reschedule).

Built for the KI-OS workflow: it replaces the ad-hoc AppleScript snippets used for /review, the purchase-decision framework and the loop↔Things sync with a proper tool surface.

How it works

All access goes through AppleScript (osascript), invoked with an on run argv handler so user-provided values (task titles, notes, tags) are passed as real arguments — never interpolated into the script, so there is no injection risk. No external Python dependency beyond the MCP SDK; nothing reads the Things SQLite database directly, which keeps writes safe and avoids schema coupling.

Requires the Things 3 app to be installed and running. On first use macOS will ask to grant Automation permission to control Things 3 — approve it for the host process (Claude / your terminal).

Related MCP server: Things MCP

Tools

Write tools accept either todo_id (exact, safest — e.g. an id from create_todo) or a name query (exact=True for an exact match instead of a substring).

Todo objects carry: id, name, status, tags, due (deadline, ISO), when (scheduled/activation date, ISO), project, area, completion (ISO), notes. Dates are YYYY-MM-DD strings; when accepts today, tomorrow, anytime, someday or an ISO date.

Install

cd ~/workspace/things3-mcp-server
python3 -m venv .venv
.venv/bin/pip install -e .

Register with Claude Code (user scope)

claude mcp add things3 --scope user -- \
  ~/workspace/things3-mcp-server/.venv/bin/things3-mcp-server

Design note

The MCP stays a generic Things wrapper. Domain semantics — e.g. the ADHS 48h purchase-decision rule (48h-Liste tag, +2 days, then Spontankauf +7) — live in the KI-OS skills, not here. update_todo(query, tags=..., move_to_list="Anytime") is exactly the primitive the 48h→Spontankauf transition needs.

Scope / non-goals

• The interactive "Einkäufe ADHS" Shortcut is deliberately not wrapped (it needs UI dialogs and stays manual).

• No delete tool by design — cancel_todo (reversible) covers "drop this task" (e.g. a rejected purchase decision); hard deletion is intentionally left out.