things-mcp

To add the Things MCP server to Claude Code, use the mcp add-json command.

For the current project:

claude mcp add-json things '{"command":"uvx","args":["things-mcp"]}'

Globally (across all projects):

claude mcp add-json -s user things '{"command":"uvx","args":["things-mcp"]}'

The Things MCP server allows Claude to interact with your Things 3 task data.

Prerequisites

• macOS: Things 3 is Mac-only.
• Things 3 Configuration: Open Things 3, go to Settings → General, and ensure "Enable Things URLs" is turned on.
• uv: Install the Python package manager via Homebrew: brew install uv.
• MCP Client: Such as Claude Desktop or Claude Code.

Installation via uvx

You can run the server directly using uvx in any MCP client configuration:

uvx things-mcp

You can install the Things MCP server in Claude Desktop using two methods:

Option 1: One-Click Install (Recommended)

1. Download the latest .mcpb file from the releases page.
2. Double-click the file to install.

Option 2: Manual Configuration

1. Open Claude Desktop and navigate to Claude → Settings → Developer → Edit Config.
2. Add the following configuration to your mcpServers object:

{
  "mcpServers": {
    "things": {
      "command": "uvx",
      "args": ["things-mcp"]
    }
  }
}

3. Save the file and restart Claude Desktop.

By default, the server uses stdio transport. To enable remote access via HTTP, set the following environment variables:

Example Command

THINGS_MCP_TRANSPORT=http THINGS_MCP_HOST=0.0.0.0 THINGS_MCP_PORT=8000 uvx things-mcp

The formatters.py module provides utility functions to convert raw Things item dictionaries (todos, projects, areas, headings, and tags) into human-readable string representations. These formatters are used to present structured data from the Things database in a clear, text-based format suitable for LLM consumption or logging.

Key formatting behaviors include:

• Timestamps: Automatically calculates and appends human-readable age (e.g., "3 days ago") for created and modified fields.
• Hierarchy: Resolves and displays parent relationships such as Projects, Areas, and Headings.
• Inheritance: For todos, if a task has a specific start date but its parent project is set to Someday, the formatter notes the inheritance.
• Checklists: Formats checklist items within a todo using ✓ for completed and ☐ for incomplete items.

If the server is not working, check the following:

1. Things 3 Status: Ensure Things 3 is installed and has been opened at least once to create the database.
2. URL Scheme: Ensure "Enable Things URLs" is turned on in Things → Settings → General.
3. uvx Path: If Claude Desktop cannot find uvx, install it via Homebrew (brew install uv) or provide the absolute path in your config (find it using which uvx).

The server's transport method and network settings can be configured via environment variables:

When using tools like add-todo, add-project, update-todo, or update-project, the when parameter accepts several formats for scheduling:

• Keywords: today, tomorrow, evening, anytime, someday.
• Date: YYYY-MM-DD (e.g., 2024-01-15).
• DateTime with reminder: YYYY-MM-DD@HH:MM (e.g., 2024-01-15@14:30).

The search-advanced tool allows for complex filtering of todos. Supported parameters include:

• status: Filter by incomplete, completed, or canceled.
• start_date: Filter by start date (YYYY-MM-DD).
• deadline: Filter by deadline (YYYY-MM-DD).
• tag: Filter by tag name.
• area: Filter by area UUID.
• type: Filter by item type (to-do, project, or heading).
• last: Filter by creation date using relative strings (e.g., '3d' for last 3 days, '1w' for last week).

The update-todo tool provides granular control over a todo's tags and checklist:

Tags

• tags: Replace all existing tags with this list.
• add_tags: Append new tags to the existing list.

Checklist

• checklist_items: Replace the entire checklist with this list.
• prepend_checklist_items: Add these items to the top of the checklist.
• append_checklist_items: Add these items to the bottom of the checklist.

The bulk-update-todos tool applies a single change to a list of todo UUIDs. This requires the Things auth token to be enabled in Things 3 (Settings → General → Enable Things URLs → Manage).

Required Parameter:

• ids: A list of todo UUIDs to update.

Available Operations:

• list / list_id: Move all todos into a project or area (by title or UUID).
• tags / add_tags: Replace or append tags on all todos.
• when: Reschedule all todos (accepts keywords or YYYY-MM-DD).
• deadline: Set a deadline on all todos (YYYY-MM-DD).
• heading / heading_id: Move all todos under a heading (by title or UUID).
• completed / canceled: Mark all todos as completed or canceled.