things-mcp by mgomes - MCP Server

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, and json as 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": "/Users/mgomes/Documents/Work/moonbase/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": "/Users/mgomes/Documents/Work/moonbase/things-mcp/bin/things-mcp",
      "args": ["-activate"]
    }
  }
}

MCP Client Configuration

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 /Users/mgomes/Documents/Work/moonbase/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 /Users/mgomes/Documents/Work/moonbase/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":"/Users/mgomes/Documents/Work/moonbase/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 metadata
things-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 query
things-search – open the search UI with optional query text
things-version – show the Things build/scheme version dialog
things-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.