Things 3

by excelsier

26 stars

259 downloads

Not rated

GitHub

About

Integrates with the Things 3 task management app to enable creating tasks, managing projects, and analyzing productivity patterns through natural language commands

Details

Author: excelsier
Repository: excelsier/things-fastmcp
GitHub stars: 26
Downloads: 259
License: Other
Categories: Productivity, Developer Tools, Design, AI, Search, Infrastructure, Project Management, Frontend, Other

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name Things 3

Command (node, npx, python, etc.) uv
Arguments
- Argument 1 --directory
- Argument 2 /ABSOLUTE/PATH/TO/PARENT/FOLDER/things-mcp
- Argument 3 run
- Argument 4 things_server.py
Environment
- THINGS_AUTH_TOKEN your-token-here
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

pip install things-mcp

Or using uv (recommended):

uv pip install things-mcp

There are multiple ways to install and use the Things MCP server:

After installation, you can run the server directly:

things-mcp

Install uv if you haven't already:

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

Restart your terminal afterwards.

uv venv
uv pip install -r pyproject.toml

Run the configuration tool to set up your Things authentication token:

python configure_token.py

This will guide you through the process of configuring your Things authentication token, which is required for the MCP server to interact with your Things app.

Edit the Claude Desktop configuration file:

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

Add the Things server to the mcpServers key in the configuration file (be sure to update the path to the folder where you installed these files):

{

    "mcpServers": {

        "things": {

            "command": "uv",

            "args": [

                "--directory",

                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/things-mcp",

                "run",

                "things_server.py"

            ]

        }

    }

}

The Things URL scheme requires an authentication token. You can find it in Things → Settings → General.

Option 1: Set via configuration script

python configure_token.py

Option 2: Set via environment variable

export THINGS_AUTH_TOKEN="your-token-here"

Option 3: Manually create config file

mkdir -p ~/.things-mcp

echo '{"things_auth_token": "your-token-here"}' > ~/.things-mcp/config.json

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

- Required for all URL scheme operations (create, update, delete)
- Without a token, Things will prompt for authentication on each operation

The Things MCP server requires an authentication token to interact with the Things app. This token is used to authorize URL scheme commands.

1. Open Things app on your Mac
2. Go to Things → Preferences (⌘,)
3. Select the General tab
4. Make sure "Enable Things URLs" is checked
5. Look for the authentication token displayed in the preferences window

Run the included configuration tool to set up your token:

python configure_token.py

This interactive script will prompt you for your token and save it securely in your local configuration.


uv venv
uv pip install -e ".[dev]"  # Install in development mode with extra dependencies

`get-inbox`

Get todos from Inbox

`get-today`

Get todos due today

`get-upcoming`

Get upcoming todos

`get-anytime`

Get todos from Anytime list

`get-someday`

Get todos from Someday list

`get-logbook`

Get completed todos

`get-trash`

Get trashed todos

`get-todos`

Get todos, optionally filtered by project

`get-projects`

Get all projects

`get-areas`

Get all areas

`get-tags`

Get all tags

`get-tagged-items`

Get items with a specific tag

`search-todos`

Simple search by title/notes

`search-advanced`

Advanced search with multiple filters

`get-recent`

Get recently created items

`add-todo`

Create a new todo with full parameter support

`add-project`

Create a new project with tags and todos

`update-todo`

Update an existing todo

`update-project`

Update an existing project

`delete-todo`

Delete a todo (moves to trash)

`delete-project`

Delete a project (moves to trash)

`show-item`

Show a specific item or list in Things

`search-items`

Search for items in Things

List Views

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

Basic Operations

- get-todos - Get todos, optionally filtered by project - get-projects - Get all projects - get-areas - Get all areas

Tag Operations

- get-tags - Get all tags - get-tagged-items - Get items with a specific tag

Search Operations

- search-todos - Simple search by title/notes - search-advanced - Advanced search with multiple filters

Time-based Operations

- get-recent - Get recently created items

Modification Operations

- add-todo - Create a new todo with full parameter support - add-project - Create a new project with tags and todos - update-todo - Update an existing todo - update-project - Update an existing project - delete-todo - Delete a todo (moves to trash) - delete-project - Delete a project (moves to trash) - show-item - Show a specific item or list in Things - search-items - Search for items in Things

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

Linux

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

Macos

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

Windows

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

Things MCP Server

This Model Context Protocol (MCP) server lets you use Claude Desktop to interact with your task management data in Things app. You can ask Claude to create tasks, analyze projects, help manage priorities, and more.

This server leverages the Things.py library and the Things URL Scheme, with additional reliability features including:

- Robust error handling with exponential backoff and retry mechanisms
- Circuit breaker pattern to prevent cascading failures
- Dead letter queue for failed operations
- Intelligent caching for improved performance
- Comprehensive logging with structured JSON output
- AppleScript bridge for operations that fail with URL schemes
- Rate limiting to prevent overwhelming the Things app
- Extensive test suite for reliability

Why Things MCP?

This MCP server unlocks the power of AI for your task management:

- Natural Language Task Creation: Ask Claude to create tasks with all details in natural language
- Smart Task Analysis: Get insights into your projects and productivity patterns
- GTD & Productivity Workflows: Let Claude help you implement productivity systems
- Seamless Integration: Works directly with your existing Things 3 data

Features

Installation Options

There are multiple ways to install and use the Things MCP server:

Option 1: Install from PyPI (Recommended)

Prerequisites

Python 3.12+ Claude Desktop Things 3 ("Enable Things URLs" must be turned on in Settings -> General) Things Authentication Token (required for URL scheme operations)

Installation

pip install things-mcp

Or using uv (recommended):

uv pip install things-mcp

Running

After installation, you can run the server directly:

things-mcp

Option 2: Manual Installation

Prerequisites

Python 3.12+ Claude Desktop Things 3 ("Enable Things URLs" must be turned on in Settings -> General)
Step 1: Install uv
Install uv if you haven't already:
curl -LsSf https://astral.sh/uv/install.sh | sh
Restart your terminal afterwards.
Step 2: Clone this repository

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

Step 3: Set up Python environment and dependencies

uv venv uv pip install -r pyproject.toml

Step 4: Configure Things authentication token
Run the configuration tool to set up your Things authentication token:
python configure_token.py
This will guide you through the process of configuring your Things authentication token, which is required for the MCP server to interact with your Things app.
Step 5: 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 key in the configuration file (be sure to update the path to the folder where you installed these files):

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

Step 6: Configure Authentication Token
The Things URL scheme requires an authentication token. You can find it in Things → Settings → General.
Option 1: Set via configuration script

python configure_token.py

Option 2: Set via environment variable

export THINGS_AUTH_TOKEN="your-token-here"

Option 3: Manually create config file

mkdir -p ~/.things-mcp echo '{"things_auth_token": "your-token-here"}' > ~/.things-mcp/config.json

Step 7: Restart Claude Desktop
Restart the Claude Desktop app to apply the changes.
Sample Usage with Claude Desktop
"What's on my todo list today?" "Create a todo to pack for my beach vacation next week, include a packling checklist." "Evaluate my current todos using the Eisenhower matrix." "Help me conduct a GTD-style weekly review using Things."
Tips
Create a project in Claude with custom instructions that explains how you use Things and organize areas, projects, tags, etc. Tell Claude what information you want included when it creates a new task (eg asking it to include relevant details in the task description might be helpful).

Try adding another MCP server that gives Claude access to your calendar. This will let you ask Claude to block time on your calendar for specific tasks, create todos from upcoming calendar events (eg prep for a meeting), etc.

Available Tools

List Views

Basic Operations

- get-todos - Get todos, optionally filtered by project - get-projects - Get all projects - get-areas - Get all areas

Tag Operations

- get-tags - Get all tags - get-tagged-items - Get items with a specific tag

Search Operations

- search-todos - Simple search by title/notes - search-advanced - Advanced search with multiple filters

Time-based Operations

- get-recent - Get recently created items

Modification Operations

Tool 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')

add-todo

- title - Title of the todo - notes (optional) - Notes for the todo - when (optional) - When to schedule the todo (today, tomorrow, evening, anytime, someday, or YYYY-MM-DD) - deadline (optional) - Deadline for the todo (YYYY-MM-DD) - tags (optional) - Tags to apply to the todo - list_title or list_id (optional) - Title or ID of project/area to add to - heading (optional) - Heading to add under - checklist_items (optional) - Checklist items to add

update-todo

- id - ID of the todo to update - title (optional) - New title - notes (optional) - New notes - when (optional) - New schedule - deadline (optional) - New deadline - tags (optional) - New tags - completed (optional) - Mark as completed - canceled (optional) - Mark as canceled

…

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

get-inbox

get-today

get-upcoming

get-anytime

get-someday

get-logbook

get-trash

get-todos

get-projects

get-areas

get-tags

get-tagged-items

search-todos

search-advanced

get-recent

add-todo

add-project

update-todo

update-project

delete-todo

delete-project

show-item

search-items

List Views

Basic Operations

Tag Operations

Search Operations

Time-based Operations

Modification Operations

Claude Desktop / Cursor

Linux

Macos

Windows

Things MCP Server

Why Things MCP?

Features

Installation Options

Option 1: Install from PyPI (Recommended)

Prerequisites

Installation

Running

Option 2: Manual Installation

Prerequisites

Step 1: Install uv

Step 2: Clone this repository

Step 3: Set up Python environment and dependencies

Step 4: Configure Things authentication token

Step 5: Configure Claude Desktop

Step 6: Configure Authentication Token

Step 7: Restart Claude Desktop

Sample Usage with Claude Desktop

Tips

Available Tools

List Views

Basic Operations

Tag Operations

Search Operations

Time-based Operations

Modification Operations

Tool Parameters

get-todos

get-projects / get-areas / get-tags

search-advanced

get-recent

add-todo

update-todo

Install

More like this

Time

Sentry

Github

Git

GitLab

Context 7

`get-inbox`

`get-today`

`get-upcoming`

`get-anytime`

`get-someday`

`get-logbook`

`get-trash`

`get-todos`

`get-projects`

`get-areas`

`get-tags`

`get-tagged-items`

`search-todos`

`search-advanced`

`get-recent`

`add-todo`

`add-project`

`update-todo`

`update-project`

`delete-todo`

`delete-project`

`show-item`

`search-items`