Things MCP

A Model Context Protocol (MCP) server for Things 3 integration. Enables Claude Desktop and Claude Code to interact with Things 3 on macOS.

Features

• Create to-dos and projects with full metadata

• Update existing to-dos and projects

• List items from any Things list (Inbox, Today, Logbook, Trash, etc.)

• Retrieve all projects, areas, and tags

• Navigate to specific items or lists

• Search within Things

• Secure AppleScript execution

• Comprehensive error handling

Requirements

• macOS with Things 3 installed

• Node.js 18 or later

• Things URL scheme enabled (automatic on first use)

Installation

Quick Start with npx (Recommended)

This will automatically download, build, and start the MCP server.

Manual Installation

1. Clone this 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

Claude Desktop Setup

1. Get your Things auth token (required for update operations):

   • Open Things → Settings → General

   • Enable Things URLs

   • Click Manage → Copy Token

2. Configure Claude Desktop:

   Open your Claude Desktop configuration file:

   ~/Library/Application Support/Claude/claude_desktop_config.json

   Add the Things MCP server to the mcpServers section:

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

   Replace your-token-here with your actual Things auth token from step 1.

3. Restart Claude Desktop to apply the configuration changes.

Alternative: Local Installation

If you prefer to install locally instead of using npx:

Usage Examples

Create a To-Do

Create a Simple Project

Create a Complex Project

Another Project Example

Update a To-Do

Add Items to Existing Project

List Tasks

View Projects

Navigate

Get Task Details

Search

View Completed Tasks

Available Tools

Creation Tools

• things_add_todo - Create a to-do with all options

• things_add_project - Create a project with sections (headings), todos, and hierarchical organization

Update Tools (requires auth token)

• things_update_todo - Update an existing to-do using JSON API for full feature support

• things_update_project - Update an existing project using JSON API for full feature support

• things_add_items_to_project - Add structured todos and headings to an existing project

Reading Tools

• things_get_inbox - List inbox items

• things_get_today - List today's items

• things_get_upcoming - List scheduled items

• things_get_anytime - List anytime items

• things_get_someday - List someday 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

All list tools support an optional max_results parameter to limit output.

Navigation Tools

• things_show - Navigate to item or list

Development

Troubleshooting

"Things 3 does not appear to be running"

Make sure Things 3 is installed and has been opened at least once.

"Authentication failed"

Check that your THINGS_AUTH_TOKEN is correctly set in the MCP configuration.

AppleScript Permissions

On first run, macOS may ask for permission to control Things. Grant this permission for the MCP to work.

Performance Issues

Use the max_results parameter when listing large collections:

License

MIT

Credits

Built with the Model Context Protocol SDK. Things is a trademark of Cultured Code GmbH & Co. KG.