things-mcp

A Model Context Protocol server for Things 3 on macOS. It lets Claude (Claude Code and Claude Desktop) read and write your tasks.

How it works — the reliable combination:

This split is deliberate: Things' own guidance warns that writing to its database can cause data loss, so this server never does. Reads open the DB read-only; every mutation goes through the URL scheme.

Read backends: SQLite vs AppleScript

Reads have two backends. By default the server auto-selects: SQLite if it can reach the database (Full Disk Access granted), otherwise AppleScript.

Why this matters for Claude Desktop: granting Full Disk Access to Claude.app does not always propagate to the process it spawns, so SQLite can stay blocked. The AppleScript backend sidesteps that entirely — set THINGS_MCP_BACKEND=applescript (below) and you only need the one-click Automation prompt.

Configuration (env vars)

• THINGS_MCP_BACKEND — auto (default) · sqlite · applescript.

• THINGS_AUTH_TOKEN — the Things URL token for updates/complete/cancel. Only needed on the AppleScript backend (where the token can't be read from the DB). Copy it from Things → Settings → General → Enable Things URLs → Manage.

• THINGSDB — override the database path (rarely needed; it's auto-discovered).

Related MCP server: Things MCP

Requirements

• macOS (Things is Mac/iOS only; this server must run on the same Mac as Things).

• Things 3, opened at least once so its database exists.

• Python ≥ 3.11 and uv.

Setup — do this first (it's the #1 reason task servers "don't work")

1. Grant Full Disk Access (required for reads)

The Things database lives in a macOS-protected container. Without Full Disk Access, macOS blocks all reads with Operation not permitted — and naive servers silently report "no tasks found" instead of explaining why.

Grant it to the app that launches this server:

• Claude Code → your terminal app (Terminal, iTerm2, etc.).

• Claude Desktop → Claude.app.

System Settings → Privacy & Security → Full Disk Access → enable that app, then fully quit and reopen it.

2. Enable Things URLs (required for writes)

Things → Settings → General → Enable Things URLs. This lets the server create and update items, and provides the auth token (read automatically — you never paste it).

Install

No clone required — uv builds and runs it straight from GitHub.

Claude Code

claude mcp add -s user things -- uvx --from git+https://github.com/than/things-mcp things-mcp

(-s user makes it available in every project. Drop it to scope the server to the current project only.)

Claude Desktop

Recommended: the AppleScript backend — no Full Disk Access needed, just one Automation click. (On Desktop, Full Disk Access granted to Claude.app often does not reach the process it spawns, so SQLite can stay blocked.)

1. Copy your token: Things → Settings → General → Enable Things URLs → Manage → copy the token.

2. Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add the things server (paste your token):

   {
     "mcpServers": {
       "things": {
         "command": "uvx",
         "args": ["--from", "git+https://github.com/than/things-mcp", "things-mcp"],
         "env": {
           "THINGS_MCP_BACKEND": "applescript",
           "THINGS_AUTH_TOKEN": "paste-token-here"
         }
       }
     }
   }

3. Quit Claude Desktop (⌘Q) and reopen.

4. Ask it "show my Things today" → click Allow on the "uvx wants to control Things" prompt.

Prefer fast SQLite instead? Drop the env block, grant Full Disk Access to Claude.app (and, if reads still fail, to the uvx/interpreter binary), then relaunch.

Local checkout (development)

If you've cloned the repo and want to run your working copy:

claude mcp add -s user things -- uv run --directory /ABSOLUTE/PATH/things-mcp things-mcp

Verify

Ask Claude to run the doctor tool. All three checks should pass:

• database_found — the Things DB was located.

• database_readable — Full Disk Access is granted (no TCC block).

• things_urls_enabled — the auth token is available.

Any failure comes with the exact fix.

Tools

Reads

Writes

Diagnostics

Known limitations (v1)

• Creating areas or tags isn't supported — the URL scheme can't create them (only AppleScript can). Areas and tags are read-only; you can apply existing tags when adding/updating.

• Write confirmation is best-effort. The URL scheme doesn't return the new item's ID, so after an add the server reads the list back and tries to match by title. If it can't confirm, it says so rather than inventing an ID.

• macOS only, by nature.

Development

uv sync
uv run pytest          # full suite runs against a vendored fixture DB — no live Things needed

Read tests run against a Things-schema fixture database vendored from things.py (see tests/fixtures/README.md).

Credits

• Reading is powered by things.py (MIT).

• Built against Cultured Code's official docs: URL scheme, JSON command, AppleScript, AI tools & safe integration.

License

MIT — see LICENSE.