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.

Related MCP server: Things MCP

Tools

Composite reads, each replacing several separate MCP calls:

Batch writes via the URL scheme:

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

License

MIT