📌Overview

Purpose: The Things MCP Server enables users to leverage the Claude Desktop interface to efficiently manage task-related data within the Things app.

Overview: This server integrates the Model Context Protocol (MCP) with the Things app, allowing users to utilize Claude to create, analyze, and prioritize tasks in a streamlined manner. It utilizes the Things.py library and supports the predefined Things URL Scheme for seamless interaction.

Key Features:

Access to Major Lists: Provides comprehensive access to key Things lists such as Inbox, Today, and Upcoming for easy management of tasks.
Project and Area Management: Allows users to organize and manage projects and areas effectively for streamlined task allocation.
Advanced Search Capabilities: Enables refined search functionalities for finding specific tasks using various filters (e.g., status, deadlines, tags).
Detailed Item Information: Displays in-depth information about tasks, including checklists, enhancing user visibility and task tracking.
Support for Nested Data: Facilitates complex organizational structures by allowing tasks, projects, and areas to be nested within one another.

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.

Features

Access to all major Things lists (Inbox, Today, Upcoming, etc.)
Project and area management
Tag operations
Advanced search capabilities
Recent items tracking
Detailed item information including checklists
Support for nested data (projects within areas, todos within projects)

Installation (for Claude Desktop)

Prerequisites

Python 3.12+
Claude Desktop
Things 3 ("Enable Things URLs" must be turned on in Settings -> General)

Steps

Install uv if you haven't already:
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Restart your terminal afterwards.

Clone this 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

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 (update the path accordingly):

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

Restart the Claude Desktop app.

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 packing 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 explaining how you use Things and organize areas, projects, tags, etc. Tell Claude what information you want included when it creates a new task (e.g., relevant details in the task description).
Consider adding another MCP server that gives Claude access to your calendar to enable task scheduling based on your calendar events.

Available Tools

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

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

Troubleshooting

The server handles errors such as invalid UUIDs, missing parameters, Things database access errors, and data formatting errors. All errors are logged with descriptive messages.

To review the MCP logs from Claude Desktop, run this in the Terminal:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log