Things App

This MCP server lets you control Things 3 on macOS through an MCP client, enabling AI assistants to create, read, update, and manage your tasks directly in Things. It exposes a read/write bridge that connects your assistant’s requests to Things via the Things URL scheme and AppleScript/JXA queries, helping you automate task management with confidence.

How to use

You can use an MCP client to send write and read operations to Things through this server. For write operations, you construct Things URLs to create or update to-dos and projects, or navigate to specific lists. For read operations, you query your Things data to retrieve to-dos, projects, areas, or tags. If your workflow requires updating existing items, you must supply an authorization token.

How to install

Follow these steps to install and run the server locally. You will either clone the project and build it, or install it globally for convenient access.

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

# Start the MCP server locally (if you have a start script)
npm run start

Configuration and usage notes

Configure your MCP client to connect to this server through a local process. The following configuration examples show how to run the server via Node.js and point your client to the compiled entry point. You can also pass an authentication token to enable update operations.

# Claude Desktop configuration
# Path: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "things": {
      "command": "node",
      "args": ["/path/to/things-app-mcp/dist/index.js"]
    }
  }
}

# Cursor MCP settings
# Path: ~/.cursor/mcp.json
{
  "mcpServers": {
    "things": {
      "command": "node",
      "args": ["/path/to/things-app-mcp/dist/index.js"]
    }
  }
}

# Gemini CLI registration
gemini mcp add things node /path/to/things-app-mcp/dist/index.js

Auth token configuration for updates

To perform update-todo and update-project operations, you can supply an authentication token. You have two options: environment variable configuration or passing the token as a parameter in your requests.

# Option 1: Environment variable (recommended)
# Claude Desktop or client config example
{
  "mcpServers": {
    "things": {
      "command": "node",
      "args": ["/path/to/things-app-mcp/dist/index.js"],
      "env": {
        "THINGS_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

# Option 2: Pass as parameter when environment variable is not set
# Copy the authorization token from Things > Settings > General > Enable Things URLs > Manage
# Then pass it as authToken in the request

Usage examples

Examples illustrate common tasks you can perform through the MCP server. Use the appropriate write or read operation with your MCP client.

# Add a to-do called 'Buy groceries' scheduled for today with tag 'Errand'
# The AI will call add-todo with a payload like:
{
  "title": "Buy groceries",
  "when": "today",
  "tags": "Errand"
}

# Create a project called 'Launch Website' in the Work area with to-dos
{
  "title": "Launch Website",
  "area": "Work",
  "todos": "Design mockups\nBuild frontend\nDeploy"
}

# Read from Today list
{
  "list": "Today"
}

# Update a to-do using its ID and an auth token
# The system will search for the to-do, obtain its ID, and perform the update

Things URL Scheme reference and read operations

This server supports the full Things URL Scheme v2 for write operations and AppleScript/JXA-based read operations. Use the supported date formats, built-in list IDs, and JSON command object types as shown in your client requests.

Architecture and how it works

The MCP server bridges your client requests to Things by constructing Things URLs for write actions and using AppleScript/JXA for reads. It runs as a local process on your Mac and responds with structured data suitable for your AI assistant to present and act upon.

Development and contributing notes

If you contribute, ensure you install dependencies, build, and test your changes. Use the standard project workflow to run a local server instance and verify end-to-end interactions with Things.

Available tools

add-todo

Create a new to-do with title, notes, dates, tags, checklist, and project/area assignment.

add-project

Create a new project with to-dos, notes, dates, tags, and area assignment.

update-todo

Update an existing to-do; requires an auth-token.

update-project

Update an existing project; requires an auth-token.

show

Navigate to a list, project, area, tag, or a specific to-do.

search

Open the Things search screen.

add-json

Create complex structures via the Things JSON command.

get-todos

Retrieve to-dos from a list, 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 or notes content.

get-recent-todos

Get recently modified to-dos.