Things3

This MCP server enables you to manage Things3 on macOS through 25 specialized tools, letting you create, read, update, and organize tasks, projects, areas, and tags with automatic handling and error correction. It’s designed to be used by AI assistants and other MCP clients to interact with Things3 efficiently and reliably.

How to use

Install and run the Things3 MCP Server locally or connect to it from your MCP client. You can use the server in three main ways: via npx for a quick start, by installing the package globally with npm, or by running a local build with node. Each method exposes the same set of MCP endpoints to manage TODOs, projects, areas, tags, and logbook data in Things3.

How to install

Prerequisites: you need macOS, Things3 installed, and Node.js version 16.0.0 or newer. Ensure AppleScript access is allowed in System Settings.

Quick start with npx

{
  "mcpServers": {
    "things3": {
      "command": "npx",
      "args": ["things3-mcp@latest"],
      "env": {
        "THINGS3_AUTH_TOKEN": "your_auth_token_here"
      }
    }
  }
}

Install from npm

Install the MCP server globally, then reference it in your MCP client configuration.

npm install -g things3-mcp

Install from source and run locally

Clone the project, install dependencies, and build. Then run the server from the built dist index.

# Clone the repository
git clone https://github.com/urbanogardun/things3-mcp.git
cd things3-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start from the built dist (example for local run)
node dist/index.js

Configure your MCP client

Add a server entry in your MCP client configuration that points to one of the available run methods. Use the same env variable for the authorization token to enable update operations in Things3.

Environment variables

The server requires your Things3 authorization token for update operations. Set this token in your environment when starting the server.

Notes on using checklists and tags

Be aware of how checklist items are created and how tags are auto-generated. Some advanced features rely on Things URLs to create items with checklists, which may briefly bring Things3 to the foreground. Tags referenced in operations are created automatically if they do not exist yet.

Troubleshooting and tips

If Things3 does not respond, verify that Things3 is running, and ensure AppleScript automation permissions are granted. Use a direct AppleScript test to confirm access. For connection issues, ensure your MCP client points to the correct local host and port where the server runs.

Available tools

todos_list

List TODOs with flexible filtering and search options.

todos_get

Get detailed information about a specific TODO by its ID.

todos_create

Create a new TODO with full property support and automatic tag creation.

todos_update

Update properties of an existing TODO and auto-create missing tags.

todos_complete

Mark one or more TODOs as complete.

todos_uncomplete

Mark one or more TODOs as incomplete.

todos_delete

Delete one or more TODOs permanently.

projects_list

List projects with optional area and completion filtering.

projects_get

Get detailed information about a project.

projects_create

Create a new project with optional tags and headings.

projects_update

Update project properties and auto-create missing tags.

projects_complete

Mark a project as complete.

projects_delete

Delete projects from Things3.

areas_list

List all areas with optional hidden areas.

areas_create

Create a new area.

areas_delete

Delete areas from Things3.

tags_list

List all tags with hierarchy information.

tags_create

Create a new tag, optionally under a parent tag.

tags_add

Add tags to items, auto-creating missing tags.

tags_remove

Remove tags from items.

tags_delete

Delete tags completely from Things3.

bulk_move

Move multiple TODOs to a project or area.

bulk_updateDates

Update dates for multiple TODOs.

logbook_search

Search completed items in the logbook within a date range.

system_launch

Ensure Things3 is running and ready.