Things MCP
stdio MCP server for the Things macOS app
Installation
npx things-mcpAsk AI about Things MCP
Powered by Claude Β· Grounded in docs
I know everything about Things MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Things MCP
things-mcp lets your coding agent (Claude, Cursor, Gemini, Copilot, etc.) drive the Things task manager on macOS via its documented URL scheme. The server wraps each Things command as a Model Context Protocol (MCP) tool so your assistant can create, update, and reveal todos and projects without private APIs.
Key Features
- First-class Things commands β Exposes
add,add-project,update,update-project,show,search,version, andjsonas MCP tools. - Safe URL dispatch β Normalizes outgoing URLs (e.g. spaces as
%20) and supports optional foreground activation. - Composable toolkit β Each tool returns the invoked Things URL, making it easy to log or retry actions in agents.
Disclaimers
things-mcp launches Things through its URL scheme. Any MCP client with access to the server can navigate your task lists or create/update items. Only enable the server for trusted assistants and users.
Requirements
- macOS with Things installed and βThings URLsβ enabled in Things β Settings β General.
- Go
1.25.2(the repo uses the Go toolchain manager).
Getting Started
Clone the repo, then build and test:
make test
make build # outputs bin/things-mcp
Start the server. By default Things stays in the background; pass ARGS="-activate" to tell the binary to bring Things to the front after each command:
make run # launch with background URLs
make run ARGS="-activate" # launch and foreground Things each time
Add the following MCP server config to your client (adjust the binary path if needed):
{
"mcpServers": {
"things-mcp": {
"command": "/your/local/path/things-mcp/bin/things-mcp",
"args": []
}
}
}
Pass "-activate" or other flags in the args array when you want to foreground Things:
{
"mcpServers": {
"things-mcp": {
"command": "/your/local/path/things-mcp/bin/things-mcp",
"args": ["-activate"]
}
}
}
MCP Client Configuration
Codex CLI
Run:codex mcp add things-mcp -- /your/local/path/things-mcp/bin/things-mcp
Add -activate after the binary path if you want Things to pop to the foreground:
codex mcp add things-mcp -- /your/local/path/things-mcp/bin/things-mcp -activate
Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` and add the snippet above under `mcpServers`. Restart Claude Desktop afterwards.Claude Code CLI
Run:claude mcp add things-mcp /your/local/path/things-mcp/bin/things-mcp
Add -activate after the binary path if you want Things to pop to the foreground.
Cursor
Go to **Settings β MCP β New MCP Server**, choose βStdioβ, set the command to the built binary path, and optionally add `-activate` in arguments. Alternatively use the deeplink builder inside Cursor with the JSON above.Gemini CLI
gemini mcp add things-mcp /your/local/path/things-mcp/bin/things-mcp
Supply --args -activate if you want foreground launches.
GitHub Copilot CLI
Inside the Copilot prompt run `/mcp add`, choose βLocalβ server type, set command to the binary path, and leave arguments blank (or `-activate` as desired).JetBrains AI Assistant / Junie
Navigate to **Settings β Tools β AI Assistant β Model Context Protocol**, click **Add**, set the command field to the built binary, and specify any arguments. Repeat the same flow for Junie under **Settings β Tools β Junie β MCP Settings**.VS Code / Copilot Chat
Run:code --add-mcp '{"name":"things-mcp","command":"/your/local/path/things-mcp/bin/things-mcp","args":[]}'
Reopen VS Code so Copilot Chat loads the server.
Warp
Open **Settings β AI β Manage MCP Servers β + Add**, select βLocalβ, and use the standard command/args snippet.Tools
things-addβ create todos (supports multi-title batches, tags, deadlines, etc.)things-add-projectβ create projects with optional child todos and metadatathings-updateβ update existing todos (requires Things auth token)things-update-projectβ update existing projects (requires auth token)things-showβ reveal a list/project/todo or quick find querythings-searchβ open the search UI with optional query textthings-versionβ show the Things build/scheme version dialogthings-jsonβ invoke the JSON batch command for complex imports
Each tool returns structured output with the dispatched URL so clients can display or reuse it.
Testing
Run the suite with:
make test
The tests cover URL encoding, validation, and JSON compaction logic.
Known Limitations
- The Things URL scheme is write- and navigation-focused; it does not provide endpoints to list existing todos or projects. Use Things directly (or another integration) when you need to read structured data.
