Things App MCP server for AI agents

This MCP server allows you to connect Claude Desktop with your Things app, enabling AI-powered task management. You can use Claude to create tasks, analyze projects, manage priorities, and interact with your Things data through natural language.

Prerequisites

Python 3.12+
Claude Desktop
Things 3 (with "Enable Things URLs" turned on in Settings → General)

Installation

Set Up the Server

First, install the uv package manager:

curl -LsSf https://astral.sh/uv/install.sh | sh

Restart your terminal after installation.

Next, clone the repository:

git clone https://github.com/hald/things-mcp

Install the required Python packages:

cd things-mcp
uv venv
uv pip install -r pyproject.toml

Configure Claude Desktop

Edit the Claude Desktop configuration file:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add the Things server to the mcpServers section (replace the path with your actual installation path):

{
    "mcpServers": {
        "things": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/things-mcp",
                "run",
                "things_server.py"
            ]
        }
    }
}

Restart the Claude Desktop app to apply the changes.

Using with Claude

After installation, you can interact with Things through Claude using natural language. Here are some example prompts:

"What's on my todo list today?"
"Create a todo to pack for my beach vacation next week, include a packing checklist."
"Evaluate my current todos using the Eisenhower matrix."
"Help me conduct a GTD-style weekly review using Things."

Tips for Better Results

Create a Claude project with custom instructions explaining your Things organization system
Specify what information you want included when creating new tasks
Consider adding another MCP server for calendar access to enable task-calendar coordination

Available Functions

List Views

get-inbox - View Inbox todos
get-today - View todos due today
get-upcoming - View upcoming todos
get-anytime - View Anytime list
get-someday - View Someday list
get-logbook - View completed todos
get-trash - View trashed todos

Basic Operations

get-todos - Retrieve todos (can filter by project)
get-projects - List all projects
get-areas - List all areas

Tag Operations

get-tags - List all tags
get-tagged-items - Find items with specific tags

Search Operations

search-todos - Basic search by title/notes
search-advanced - Advanced multi-criteria search

Time-based Operations

get-recent - View recently created items

Function Parameters

get-todos

project_uuid (optional) - Filter todos by project
include_items (optional, default: true) - Include checklist items

get-projects / get-areas / get-tags

include_items (optional, default: false) - Include contained items

search-advanced

status - Filter by status (incomplete/completed/canceled)
start_date - Filter by start date (YYYY-MM-DD)
deadline - Filter by deadline (YYYY-MM-DD)
tag - Filter by tag
area - Filter by area UUID
type - Filter by item type (to-do/project/heading)

get-recent

period - Time period (e.g., '3d', '1w', '2m', '1y')

Troubleshooting

If you encounter issues, you can review the MCP logs from Claude Desktop:

# Follow logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

The server includes error handling for invalid UUIDs, missing parameters, database access errors, and data formatting problems.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "things" '{"command":"uv","args":["--directory","/ABSOLUTE/PATH/TO/PARENT/FOLDER/things-mcp","run","things_server.py"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "things": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/things-mcp",
                "run",
                "things_server.py"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "things": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/things-mcp",
                "run",
                "things_server.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect