Things App

🚀 Things MCP Server

This Model Context Protocol (MCP) server enables you to use Claude Desktop to interact with the task management data in the Things app. You can ask Claude to create tasks, analyze projects, assist in managing priorities, etc.

The server utilizes 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 functionality
• Tracking of recent projects
• Detailed task information, including checklists
• Support for nested data (projects within areas, to-dos within projects)

📦 Installation Guide (for Claude Desktop)

Prerequisites

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

Installation Steps

1. If uv is not installed, install it:

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

Restart your terminal.

2. Clone this repository:

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

3. Install the required Python packages:

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

4. Edit the Claude Desktop configuration file:

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

Add the following content to the JSON array:

{
  "mcpEndpoints": [
    {
      "name": "Things",
      "url": "http://localhost:9001"
    }
  ]
}

💻 Usage Examples

Basic Usage

Here are some example questions for using the server in Claude Desktop:

• List all projects and to-dos.
• Create new tasks or projects.
• Filter tasks by due date.
• Update the status or attributes of existing tasks.

💡 Usage Tip

• Enable logging for the Things database in settings for better debugging and monitoring:

defaults write com.culturedcode.Things-MacOS developer-mode -bool true

• Use the poetry run command to run the server and isolate the dependency environment.

📚 Documentation

Available Tools

Query Tool

• /items
  Retrieve all projects and to-dos in the Things database. Supports paginated loading of more data.

Creation Tool

• /items/create
  Create new tasks or projects in Things.

Update Tool

• /items/update
  Update the attributes and status of existing tasks or projects.

Tool Parameters

Query Tool (/items)

Creation Tool (/items/create)

Update Tool (/items/update)

🔧 Technical Details

Troubleshooting

The server includes handling for the following errors:

• Invalid UUID
• Missing required parameters
• Things database access errors
• Data format errors

All errors are logged and returned with descriptive messages. To view the MCP logs for Claude Desktop, run the following command in the terminal:

# Track the last 20 lines of logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log