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.

Related MCP server: Things MCP Server

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

Available tools

Writing (via URL scheme)

Reading (via local database, read-only)

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.