things3-mcp

A Model Context Protocol (MCP) server that connects Claude to Things 3 on macOS. Ask Claude to add to-dos and projects, search, open lists, and read your Today/Upcoming/Inbox — all from a Claude conversation.

Unofficial project. Not affiliated with, endorsed by, or supported by Cultured Code. Things 3 is a trademark of Cultured Code GmbH & Co. KG.

How it works

Things 3 doesn't expose a network API, so this server uses two different mechanisms:

• Writing (add_todo, add_project, update_todo, update_project, search, show) opens Things' URL scheme in the background via open -g things:///.... This requires Things 3 to be running.
• Reading (list_today, list_upcoming, list_projects, list_inbox, get_todo) queries Things' local SQLite database directly, in read-only mode. The URL scheme has no way to read data back, so this is the only option.

Prerequisites

• macOS with Things 3 installed and running
• Node.js 18+
• To use update_todo / update_project: enable Things URLs in Things → Settings → General → Enable Things URLs and copy the auth token shown there

This server is macOS-only and talks to a local app and a local file — it is not a remote/OAuth-capable MCP server and cannot be hosted or used from another machine.

Installation

Claude Desktop

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "things3": {
      "command": "npx",
      "args": ["-y", "@lcajigasm/things3-mcp"],
      "env": {
        "THINGS_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

Omit THINGS_AUTH_TOKEN if you don't need update_todo / update_project. Restart Claude Desktop afterwards.

Claude Code

claude mcp add things3 --env THINGS_AUTH_TOKEN=your-token-here -- npx -y @lcajigasm/things3-mcp

From source

git clone https://github.com/lcajigasm/things3-mcp.git
cd things3-mcp
npm install
npm run build

Then point Claude Desktop at the built file:

{
  "mcpServers": {
    "things3": {
      "command": "node",
      "args": ["/absolute/path/to/things3-mcp/dist/index.js"],
      "env": {
        "THINGS_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

Environment variables

| Variable | Required | Description | |---|---|---| | THINGS_AUTH_TOKEN | Only for update_todo / update_project | Auth token from Things → Settings → General → Enable Things URls. Never logged or echoed back by this server. | | THINGS_DB_PATH | No | Overrides auto-detection of the database file. Things nests it under a per-install ThingsData-<id> folder, which this server locates automatically — set this only if that detection fails for you. |

Available tools

Writing (via URL scheme)

| Tool | Description | |---|---| | add_todo | Create a to-do: title, notes, when (today/tomorrow/evening/someday/date), deadline, tags, checklist items, destination list. | | add_project | Create a project: title, notes, area, tags, initial to-dos. | | update_todo | Update a to-do by id. Requires THINGS_AUTH_TOKEN. | | update_project | Update a project by id. Requires THINGS_AUTH_TOKEN. | | search | Open Things and search for a term. | | show | Open a built-in list (Today, Upcoming, Anytime, Someday, Logbook, Inbox) or a specific project/area/to-do by id. |

Reading (via local database, read-only)

| Tool | Description | |---|---| | list_today | To-dos scheduled for Today. | | list_upcoming | To-dos scheduled for a future date or with an upcoming deadline. | | list_projects | Open (incomplete, non-trashed) projects. | | list_inbox | Unclassified to-dos in the Inbox. | | get_todo | Full detail for one to-do by id, including its checklist. |

Example prompts

• "Add a to-do 'Renew passport' with a deadline of 2026-09-01"
• "Create a project called 'Q3 planning' in my Work area with to-dos for budget, hiring, roadmap"
• "What's on my plate today?"
• "What's coming up in the next few weeks?"
• "Show me everything sitting in my Inbox"
• "Mark to-do abc-123 as completed"
• "Open Things and search for 'invoice'"

Limitations

• macOS + Things 3 only. No Windows/Linux/iOS support, no remote/hosted mode.
• Writing is fire-and-forget: the URL scheme doesn't return the created item's id, so add_todo/add_project can't tell you the new id directly (use search or list_inbox to find it afterwards).
• Reading queries Things' internal SQLite schema, which is undocumented and could change in future Things versions.
• update_todo/update_project need THINGS_AUTH_TOKEN; without it those two tools return an error, everything else still works.

Troubleshooting

"things3-mcp only works on macOS" This server calls open -g things:///... and reads a macOS-only app container path — there's no way around this.

"Could not find the Things 3 database" Make sure Things 3 is installed and has been opened at least once (the database is created on first launch).

"THINGS_AUTH_TOKEN environment variable is required" Only update_todo/update_project need it. Get it from Things → Settings → General → Enable Things URLs, then add it to your MCP config's env block.

Claude doesn't see the Things 3 tools

• Restart Claude Desktop after editing the config file
• Validate the JSON in claude_desktop_config.json (a trailing comma will break it)
• Run npx @lcajigasm/things3-mcp manually in a terminal to check for Node errors

Development

npm install
npm run dev    # watch mode via tsx
npm run build  # compile to dist/

License

MIT — see LICENSE. Not affiliated with Cultured Code.