jimfilippou/things-mcp

A Model Context Protocol (MCP) server that provides seamless integration with the Things productivity app. This server enables AI assistants to create, update, and manage your todos and projects in Things using its comprehensive URL scheme.
Features
- ✅ **Full Things URL Scheme Support** - Complete implementation of all Things URL commands
- ✅ **Create Todos** - Add single or multiple todos with rich metadata
- ✅ **Create Projects** - Build projects with nested todos and organization
- ✅ **Update Items** - Modify existing todos and projects
- ✅ **Smart Scheduling** - Support for natural language dates and times
- ✅ **Advanced Organization** - Tags, areas, headings, and checklist items
- ✅ **JSON Operations** - Complex batch operations via JSON
- ✅ **Search & Navigation** - Find and show specific items or lists
- ✅ **Proper URL Encoding** - Handles special characters and spaces correctly
Prerequisites
- **macOS** - Required for Things app integration
- **Things 3** - The Things app must be installed and running
- **Node.js** - Version 16 or higher
- **MCP Client** - Such as Claude Desktop app or any MCP-compatible client
Installation
Using npx (Recommended)
No installation required! Use directly with:
Global Installation
Configuration
Claude Desktop
Add the server to your Claude Desktop configuration file:
**macOS**: ~/Library/Application Support/Claude/claude_desktop_config.json
**Using npx (recommended):**
**Using global installation:**
Usage
Once configured, you can interact with Things through your MCP client using natural language. Here are some examples:
Creating Todos
Creating Projects
Updating Items
Organization
Available Commands
add-todo
Create a new todo with extensive customization options:
- **title/titles** - Single title or multiple titles separated by newlines
- **notes** - Rich text notes (max 10,000 characters)
- **when** - Natural language scheduling (today, tomorrow, evening, specific dates)
- **deadline** - Due dates with natural language support
- **tags** - Array of tag names for organization
- **checklist-items** - Subtasks within the todo
- **list/list-id** - Project or area assignment
- **heading/heading-id** - Specific heading within projects
- **completed/canceled** - Set completion status
- **show-quick-entry** - Show quick entry dialog
- **reveal** - Navigate to created todo
add-project
Create a new project with full configuration:
- **title** - Project name
- **notes** - Project description
- **when** - Scheduling options
- **deadline** - Project due date
- **tags** - Organization tags
- **area/area-id** - Area assignment
- **to-dos** - Array of todo titles to create within project
- **completed/canceled** - Project status
- **reveal** - Navigate to created project
update
Modify existing todos:
- **id** - Todo ID (required)
- **auth-token** - Authorization token (required)
- **title** - New title
- **notes/prepend-notes/append-notes** - Note modifications
- **when** - Reschedule
- **deadline** - Change due date
- **tags/add-tags** - Tag management
- **checklist-items** - Modify checklist
- **list/heading** - Move to different location
- **completed/canceled** - Status changes