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).

Tools

Tool	Kind	Purpose
list_todos(scope_type, scope_name, status)	read	To-dos in a list / area / project
get_today()	read	Everything in the Today list
get_inbox()	read	Everything in the Inbox
get_completed(days)	read	Recently completed to-dos (Logbook)
search_todos(query, include_completed)	read	Find to-dos by name substring
get_todo(todo_id)	read	A single to-do by id
list_areas()	read	All areas
list_projects(area)	read	Projects (optionally within an area)
list_tags()	read	All tag names
create_todo(title, notes, area, project, tags, when, deadline)	write	Create a to-do
complete_todo(query, todo_id, exact)	write	Complete open to-do(s) by name or id
cancel_todo(query, todo_id, exact)	write	Cancel open to-do(s) — reversible, no delete
update_todo(query, todo_id, tags, when, deadline, move_to_list, exact)	write	Update the first matching open to-do
add_tags(tags, query, todo_id, exact)	write	Append tags without dropping existing ones

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.