Docs: reads fail with "unable to open database file" under Claude Desktop (TCC / disclaimer helper) while writes work

[ggfevans]

Failure mode
Every read tool errors unable to open database file on the first call; URL-scheme writes (add_todo etc.) succeed. Instant failure on every call — distinct from thingsapi/things.py#125 / #141, which fail mid-scan on large databases.

Cause
The database path (~/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac/…) is TCC-protected. Claude Desktop launches MCP servers through /Applications/Claude.app/Contents/Helpers/disclaimer, which disclaims TCC responsibility: the spawned server does not inherit Claude's Full Disk Access. Granting FDA to Claude.app therefore doesn't help. Granting FDA to the actual binaries (uv / uvx / the venv python in uv's cache) works but is fragile — grants break whenever Homebrew or uv updates the binaries, and the FDA picker often greys them out.

Non-obvious knock-on: things.token() reads the auth token from the database, so update_todo / update_project / bulk_update_todos also fail while add_* still works.

Reliable fix (tested)
Run the server with THINGS_MCP_TRANSPORT=http in a context that already holds disk access (Terminal, or a login app), then bridge stdio clients:

• uvx fastmcp-remote@<version> http://127.0.0.1:8765/mcp --auth none (Python; or mcp-proxy --transport streamablehttp <url>, or npx mcp-remote <url>)
• Claude Code needs no bridge: claude mcp add --transport http things http://127.0.0.1:8765/mcp

Ask
README troubleshooting currently covers "open Things once" and the uvx PATH issue only. Happy to PR a troubleshooting section with the symptom table (read-vs-write split, token knock-on) and the tested fix ladder.

[ggfevans]

Follow-up finding for the eventual troubleshooting section — a second, subtler TCC failure mode, hit while making the HTTP-mode server persistent under launchd.

Setup: a LaunchAgent runs the server via a minimal osacompile wrapper app, so the Full Disk Access grant lives on a stable code identity rather than on uv-cache binaries (which churn on every update). This is the common pattern for FDA + launchd.

Symptom: the wrapper's FDA row is added and toggled on, yet every read still fails with unable to open database file. Toggling the row off/on changes nothing. Nothing appears in default log show output either — tccd denials are info-level:

log show --last 3m --info --predicate 'process == "tccd"' | grep -i AllFiles

yields:

Handling access request to kTCCServiceSystemPolicyAllFiles,
from Sub:{/Applications/<Wrapper>.app/Contents/MacOS/applet}
ReqResult(Auth Right: Denied (Service Policy), promptType: 1, DB Action:None)

Denied (Service Policy) + DB Action:None = tccd found no allow rule matching the requesting process: the row exists, but the identity it recorded never matches the identity computed at access time.

Root cause: osacompile output is ad-hoc signed with no CFBundleIdentifier, so TCC's identity capture (at grant time) and identity computation (at access time) fall back to different derivations and disagree. Since FDA never prompts, the mismatch is completely silent.

Fix (verified): give the wrapper a real bundle identifier, re-sign with it, then remove and re-add the FDA row — toggling does not re-capture code identity:

/usr/libexec/PlistBuddy -c 'Add :CFBundleIdentifier string com.example.mcp-shim' "/Applications/<Wrapper>.app/Contents/Info.plist"
codesign -f -s - -i com.example.mcp-shim "/Applications/<Wrapper>.app"

Access succeeds immediately after. Can fold this into the troubleshooting PR alongside the disclaimer-helper material above.