things-turbo

Composite MCP server for Things 3 on macOS. Two problems, one package:

1. Call-count bloat. Agent workflows against Things burn 10+ round trips for a morning review: projects, areas, tags, today, inbox, logbook, per-project todos. things-turbo bundles them. get_review_data is one call. get_dashboard is one call.
2. sqlite3.OperationalError: unable to open database file. The Things database lives in a TCC-protected group container. macOS decides per process, with caching, whether reads are allowed, and the answer can flip mid-session. When it flips, every read in every affected session dies at once. things-turbo ships a self-healing read path that falls back to a TCC-free SQLite mirror and keeps working.

Under 700 lines of Python. Reads go through things.py against the Things SQLite database; writes go through the official Things URL scheme, so Things itself does the writing.

Who this is for

People driving Things 3 from Claude (or any MCP client) who want fewer round trips, batch writes, and reads that survive macOS app-data protection. For one-at-a-time CRUD, upstream things-mcp may be enough; this package also ships a things-mcp-resilient entry point that runs upstream things-mcp with the self-healing read path patched in.

Tools

Composite reads, each replacing several separate MCP calls:

Tool	What it returns
get_context	Projects, areas, and tags in one call
get_dashboard	Today, inbox, upcoming, and overdue
get_review_data	Everything a weekly review needs: today, inbox, anytime/someday counts, projects with todo counts, logbook
get_project_health	Stalled-project detection: per-project last completion, next-action presence, and a health class (shipping / cruising / stalled / zombie / empty)

Batch writes via the URL scheme:

Tool	What it does
batch_update	Update many todos in one call (title, notes, when, deadline, tags, completed, canceled)
bulk_complete	Complete a list of todos
bulk_reschedule	Move a list of todos to the same date
update_checklist	Replace, append, or prepend checklist items, which the standard MCP tools can't do

Install

Requires macOS with Things 3, Python 3.12+, and uv.

Claude Code (.mcp.json or claude mcp add):

{
  "mcpServers": {
    "things-turbo": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradleyAllanDavis/things-turbo", "things-turbo"],
      "env": {
        "THINGS_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

The auth token is needed for writes only. Get it in Things: Settings > General > Enable Things URLs > Manage. To keep the token out of plain config, set THINGS_AUTH_TOKEN_CMD to a command that prints it:

"env": {
  "THINGS_AUTH_TOKEN_CMD": "op read 'op://Private/Things Auth Token/credential'"
}

The self-healing read path

things-turbo tries the live Things database first. On a TCC denial it:

1. remembers the denial for 5 minutes,
2. kickstarts the launchd mirror agent named in THINGS_MIRROR_AGENT, if set,
3. reads the mirror at THINGS_MIRROR_PATH (default ~/.cache/things-mirror/main.sqlite).

While reads are healthy, it also refreshes the mirror opportunistically (VACUUM INTO a temp file, atomic replace), so any process that still has access keeps the mirror warm for the ones that don't.

The mirror can be produced by anything that copies the Things database on a schedule. A launchd agent running sqlite3 <things-db> "VACUUM INTO '<mirror>'" under a shell with a one-time Full Disk Access grant works well; set THINGS_MIRROR_AGENT to its label and things-turbo will kickstart it on demand.

THINGSDB (the standard things.py override) always wins and never falls back.

Configuration

Variable	Purpose	Default
THINGS_AUTH_TOKEN	Things URL-scheme token, used for writes	unset
THINGS_AUTH_TOKEN_CMD	Shell command that prints the token	unset
THINGS_MIRROR_PATH	TCC-free mirror location	~/.cache/things-mirror/main.sqlite
THINGS_MIRROR_AGENT	launchd label to kickstart for a mirror refresh	unset
THINGSDB	Explicit database path (things.py standard); disables fallback	unset

License

MIT