Things App MCP

An MCP (Model Context Protocol) server for Things 3 on macOS. Enables AI assistants like Claude to create, read, update, and manage your tasks directly in Things.

Features

Write Operations (Things URL Scheme)

| Tool | Description | |------|-------------| | add-todo | Create a new to-do with title, notes, dates, tags, checklist, project/area assignment | | add-project | Create a new project with to-dos, notes, dates, tags, area assignment | | update-todo | Update an existing to-do (requires auth-token) | | update-project | Update an existing project (requires auth-token) | | show | Navigate to a list, project, area, tag, or specific to-do | | search | Open the Things search screen | | add-json | Create complex structures via the Things JSON command |

Read Operations (AppleScript/JXA)

| Tool | Description | |------|-------------| | get-todos | Get to-dos from a list (Inbox, Today, etc.), project, area, or by tag | | get-todo-by-id | Get a specific to-do by its ID | | get-projects | Get all projects | | get-project-by-id | Get a specific project by its ID | | get-areas | Get all areas | | get-tags | Get all tags | | search-todos | Search to-dos by title/notes content | | get-recent-todos | Get recently modified to-dos |

Requirements

• macOS (required for AppleScript/JXA and open command)
• Things 3 installed
• Node.js >= 18
• Things URL Scheme enabled (Things > Settings > General > Enable Things URLs)

Installation

# Clone and build
git clone <repository-url>
cd things-app-mcp
npm install
npm run build

Or install globally:

npm install -g things-app-mcp

Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

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

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

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

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

Codex

Add to ~/.codex/config.toml:

[mcp_servers.things]
command = "npx"
args = ["-y", "things-app-mcp@latest"]
startup_timeout_sec = 20
tool_timeout_sec = 120

Gemini CLI

Run the following command to register the MCP server:

gemini mcp add things npx -y things-app-mcp@latest

Auth Token Configuration

To use update-todo and update-project, you need your Things auth-token.

Option 1: Environment Variable (Recommended)

Set the THINGS_AUTH_TOKEN environment variable in your MCP client configuration. This avoids needing to pass the token with every request.

Claude Desktop:

{
  "mcpServers": {
    "things": {
      "command": "npx",
      "args": ["-y", "things-app-mcp@latest"],
      "env": {
        "THINGS_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.things]
command = "npx"
args = ["-y", "things-app-mcp@latest"]
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.things.env]
THINGS_AUTH_TOKEN = "your-token-here"

Gemini CLI: Set the environment variable in your shell configuration or pass it when running:

export THINGS_AUTH_TOKEN="your-token-here"

Option 2: Parameter

If the environment variable is not set, you must pass the token as the authToken parameter when calling update tools:

1. Open Things on Mac
2. Go to Things > Settings > General > Enable Things URLs > Manage
3. Copy your authorization token
4. Pass it as the authToken parameter when calling update tools

Usage Examples

Adding a To-Do

"Add a to-do called 'Buy groceries' scheduled for today with tags 'Errand'"

The AI will call add-todo with:

{
  "title": "Buy groceries",
  "when": "today",
  "tags": "Errand"
}

Creating a Project with To-Dos

"Create a project called 'Launch Website' in the Work area with to-dos: Design mockups, Build frontend, Deploy"

The AI will call add-project with:

{
  "title": "Launch Website",
  "area": "Work",
  "todos": "Design mockups\nBuild frontend\nDeploy"
}

Complex Project via JSON

"Create a vacation planning project with headings for Travel, Accommodation, and Activities"

The AI will call add-json with structured JSON data containing nested headings and to-dos.

Reading To-Dos

"What's on my Today list?"

The AI will call get-todos with { "list": "Today" } and return the structured data.

Updating a To-Do

"Mark the 'Buy groceries' todo as complete"

The AI will first search/get the to-do to find its ID, then call update-todo with the auth-token.

Things URL Scheme Reference

This MCP server implements the full Things URL Scheme v2:

Date Formats

| Format | Example | Description | |--------|---------|-------------| | Named | today, tomorrow, evening, anytime, someday | Built-in schedule options | | Date | 2026-03-15 | Specific date | | Date + Time | 2026-03-15@14:00 | Date with reminder | | Natural language | next friday, in 3 days | English natural language (parsed by Things) |

Built-in List IDs (for show tool)

inbox, today, anytime, upcoming, someday, logbook, tomorrow, deadlines, repeating, all-projects, logged-projects

JSON Command Object Types

| Type | Description | |------|-------------| | to-do | A task with title, notes, when, deadline, tags, checklist-items | | project | A project with title, notes, items (to-dos and headings) | | heading | A section heading within a project | | checklist-item | A checklist item within a to-do |

Architecture

things-app-mcp/
  src/
    index.ts          # MCP server entry point with all tool registrations
    things-url.ts     # Things URL scheme builder (URL construction)
    applescript.ts    # AppleScript/JXA executor (read operations)
  dist/               # Compiled JavaScript output
  package.json
  tsconfig.json

How It Works

• Write operations construct things:/// URLs and open them via macOS open command. Things processes the URL and creates/updates items accordingly.
• Read operations use JXA (JavaScript for Automation) scripts executed via osascript to query the Things database directly and return structured JSON data.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run directly
npm start

License

MIT