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)

Read Operations (AppleScript/JXA)

Automation (Batch Operations)

Key behaviors of reschedule-distant-todos:

• Items explicitly scheduled for today (activationDate = today) are always preserved

• Uses a single JSON batch update for atomic, reliable rescheduling

• daysThreshold (default: 7) controls how many days away a deadline must be to qualify

• bufferDays (default: 3) controls how many days before the deadline to set the new start date

• Supports dryRun mode to preview changes without applying them

• Annotated with destructiveHint: true so MCP clients can prompt for user confirmation

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, update-project, and reschedule-distant-todos, 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.

Cleaning Up Today

"My Today list is too cluttered. Move everything that isn't due soon to later."

The AI will call reschedule-distant-todos with { "dryRun": true } first to preview, then apply:

{
  "daysThreshold": 7,
  "bufferDays": 3,
  "dryRun": false
}

Items with deadlines 7+ days away will be rescheduled to 3 days before their deadline. Items you explicitly set to today are always preserved.

Previewing Reschedule Changes

"Show me which todos would be moved out of Today without actually changing anything"

The AI will call reschedule-distant-todos with { "dryRun": true } and return a list of what would change.

Things URL Scheme Reference

This MCP server implements the full Things URL Scheme v2:

Date Formats

Built-in List IDs (for show tool)

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

JSON Command Object Types

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)
  scripts/
    test-client.js    # Basic MCP server connectivity test
    test-all-tools.js # Integration tests for all 16 tools
    test-unit.js      # Unit tests for logic, URL builders, and edge cases (122 tests)
  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

Testing

See TESTING.md for full details.

# Unit tests (date utilities, URL builders, reschedule logic, edge cases)
# Runs anywhere - no macOS or Things 3 required
node scripts/test-unit.js

# Integration tests (all 16 tools via MCP protocol)
# Requires macOS + Things 3 for full coverage
npm run test:tools

# With write operations enabled
THINGS_MCP_TEST_ALLOW_WRITES=1 npm run test:tools

# Full suite with auth token
THINGS_AUTH_TOKEN=your-token \
THINGS_MCP_TEST_TODO_ID=some-id \
THINGS_MCP_TEST_PROJECT_ID=some-id \
npm run test:tools

License

MIT