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)

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": "node",
      "args": ["/path/to/things-app-mcp/dist/index.js"]
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "things": {
      "command": "node",
      "args": ["/path/to/things-app-mcp/dist/index.js"]
    }
  }
}

Gemini CLI

Run the following command to register the MCP server:

gemini mcp add things node /path/to/things-app-mcp/dist/index.js

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": "node",
      "args": ["/path/to/things-app-mcp/dist/index.js"],
      "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

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)
  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