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:

1. macOS: Things → Settings → General → Enable Things URLs → Manage
2. 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:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

License

MIT License - see LICENSE file for details.

Related

• Things URL Scheme Documentation
• Model Context Protocol
• Claude Desktop

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