Docs & Usage Guide

Things MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with the Things productivity app. This server enables AI assistants to create, update, and manage your todos and projects in Things using its comprehensive URL scheme.

Features

✅ Full Things URL Scheme Support - Complete implementation of all Things URL commands
✅ Create Todos - Add single or multiple todos with rich metadata
✅ Create Projects - Build projects with nested todos and organization
✅ Update Items - Modify existing todos and projects
✅ Smart Scheduling - Support for natural language dates and times
✅ Advanced Organization - Tags, areas, headings, and checklist items
✅ JSON Operations - Complex batch operations via JSON
✅ Search & Navigation - Find and show specific items or lists
✅ Proper URL Encoding - Handles special characters and spaces correctly

Prerequisites

macOS - Required for Things app integration
Things 3 - The Things app must be installed and running
Node.js - Version 16 or higher
MCP Client - Such as Claude Desktop app or any MCP-compatible client

Installation

Using npx (Recommended)

No installation required! Use directly with:

npx things-mcp

Global Installation

npm install -g things-mcp

Configuration

Claude Desktop

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Using npx (recommended):

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

Using global installation:

{
  "mcpServers": {
    "things": {
      "command": "things-mcp"
    }
  }
}

Usage

Once configured, you can interact with Things through your MCP client using natural language. Here are some examples:

Creating Todos

"Create a todo to buy groceries for tonight"
"Add a todo 'Call dentist' with a deadline of next Friday"
"Create multiple todos: milk, bread, eggs in my Shopping project"

Creating Projects

"Create a project called 'Website Redesign' in my Work area"
"Make a project 'Vacation Planning' with todos: book flights, reserve hotel, research activities"

Updating Items

"Update my 'Call dentist' todo to be due tomorrow"
"Add notes to my website project about the new color scheme"
"Mark the groceries todo as completed"

Organization

"Show my Today list"
"Search for all todos tagged with 'urgent'"
"Open the Someday list filtered by work tags"

Available Commands

add-todo

Create a new todo with extensive customization options:

title/titles - Single title or multiple titles separated by newlines
notes - Rich text notes (max 10,000 characters)
when - Natural language scheduling (today, tomorrow, evening, specific dates)
deadline - Due dates with natural language support
tags - Array of tag names for organization
checklist-items - Subtasks within the todo
list/list-id - Project or area assignment
heading/heading-id - Specific heading within projects
completed/canceled - Set completion status
show-quick-entry - Show quick entry dialog
reveal - Navigate to created todo

add-project

Create a new project with full configuration:

title - Project name
notes - Project description
when - Scheduling options
deadline - Project due date
tags - Organization tags
area/area-id - Area assignment
to-dos - Array of todo titles to create within project
completed/canceled - Project status
reveal - Navigate to created project

update

Modify existing todos:

id - Todo ID (required)
auth-token - Authorization token (required)
title - New title
notes/prepend-notes/append-notes - Note modifications
when - Reschedule
deadline - Change due date
tags/add-tags - Tag management
checklist-items - Modify checklist
list/heading - Move to different location
completed/canceled - Status changes
duplicate - Create copy before updating

update-project

Modify existing projects with similar options to update command.

show

Navigate to specific items or lists:

id - Specific item ID or built-in list (inbox, today, anytime, etc.)
query - Search by name
filter - Filter by tags

search

Search across all Things data:

query - Search terms

json

Advanced batch operations using JSON format for complex project structures.

version

Get Things app and URL scheme version information.

Authorization

Some operations (updates) require an authorization token from Things:

macOS: Things → Settings → General → Enable Things URLs → Manage
iOS: Settings → General → Things URLs

Copy your unique token and use it with update operations.

Getting Item IDs

To update specific items, you need their IDs:

macOS

Control-click on todo/project → Share → Copy Link
Control-click on list in sidebar → Share → Copy Link

iOS

Tap todo/project → toolbar → Share → Copy Link
Navigate to list → top right → Share → Copy Link

Error Handling

The server includes comprehensive error handling:

Invalid parameters are caught by Zod validation
Things URL failures are reported with clear messages
Missing authorization tokens are detected
Network and system errors are handled gracefully

Examples

Basic Todo Creation

// Creates a simple todo
{
  "title": "Buy milk",
  "when": "today",
  "tags": ["groceries"]
}

Complex Project Creation

// Creates a project with multiple todos and organization
{
  "title": "Plan Birthday Party",
  "area": "Personal",
  "when": "next week",
  "to-dos": [
    "Send invitations",
    "Order cake",
    "Buy decorations",
    "Plan menu"
  ],
  "tags": ["family", "celebration"],
  "reveal": true
}

JSON Batch Operation

// Complex structure with headings and nested todos
{
  "data": JSON.stringify([
    {
      "type": "project",
      "attributes": {
        "title": "Website Redesign",
        "area": "Work",
        "items": [
          {
            "type": "heading",
            "attributes": { "title": "Design Phase" }
          },
          {
            "type": "to-do",
            "attributes": {
              "title": "Create wireframes",
              "when": "today"
            }
          }
        ]
      }
    }
  ])
}

Troubleshooting

Things Not Opening

Ensure Things 3 is installed and updated
Check that Things URLs are enabled in settings
Verify the MCP server is running correctly

Authorization Errors

Get your auth token from Things settings
Include auth-token parameter for update operations
Ensure token is copied correctly without extra spaces

Connection Issues

Restart Claude Desktop or your MCP client
Check the configuration file syntax
Look for errors in client logs

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

🐛 Bug Reports: Open an issue on GitHub
💡 Feature Requests: Open an issue with enhancement label
📚 Documentation: Check the Things URL scheme docs
💬 Questions: Open a discussion on GitHub

Things Mcp