home / mcp / things mcp server

Things MCP Server

Provides programmatic access to Things 3 data via MCP to create, read, update, and navigate items.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "hildersantos-things-mcp": {
      "command": "npx",
      "args": [
        "github:hildersantos/things-mcp"
      ],
      "env": {
        "THINGS_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

Things MCP enables Claude Desktop and Claude Code to interact with Things 3 on macOS, letting you create, update, list, navigate, and search Things items directly from your preferred MCP client running locally or remotely.

How to use

You connect an MCP client to this server to manage Things 3 data. Use creation tools to add to‑dos and projects, reading tools to list and inspect items, and navigation tools to open specific lists or items. Update operations require authentication, so you can modify existing items after providing your Things auth token.

How to install

Prerequisites: you need macOS with Things 3 installed and Node.js 18 or later. Ensure Things URLs are enabled in Things settings.

# Quick start (recommended)
npx github:hildersantos/things-mcp

# Manual installation
# 1) Clone the repository
git clone https://github.com/hildersantos/things-mcp.git
cd things-mcp

# 2) Install dependencies
npm install

# 3) Build the project
npm run build

# 4) Start the server
npm start

Configuration and usage notes

Configure Claude Desktop to connect to the Things MCP server by adding a server entry with the appropriate command and environment variables. You will provide your Things auth token to enable update operations.

{
  "mcpServers": {
    "things-mcp": {
      "command": "npx",
      "args": ["github:hildersantos/things-mcp"],
      "env": {
        "THINGS_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

Security and permissions

On first use, macOS may ask for permission to control Things. Grant this permission to allow the MCP server to perform actions in Things. Ensure your THINGS_AUTH_TOKEN is kept secure and not exposed in client configurations.

Available tools

things_add_todo

Create a to‑do with all supported options and metadata in Things 3.

things_add_project

Create a project with sections, todos, and hierarchical organization in Things 3.

things_update_todo

Update an existing to‑do using the JSON API for full feature support (requires auth token).

things_update_project

Update an existing project with full feature support via JSON API (requires auth token).

things_add_items_to_project

Add structured to‑dos and headings to an existing project.

things_get_inbox

List items in the Things Inbox.

things_get_today

List items due today.

things_get_upcoming

List scheduled items.

things_get_anytime

List anytime items.

things_get_logbook

List completed items.

things_get_trash

List trashed items.

things_get_projects

List all active projects.

things_get_areas

List all areas.

things_get_tags

List all tags.

things_get_project

List items in a specific project (requires project_id).

things_get_area

List items in a specific area (requires area_id).

things_get_list

Get items from a specific list by name.

things_get_todo_details

Get detailed information about a specific to‑do.

things_show

Navigate to an item or list.