urbanogardun/things3-mcp

An MCP (Model Context Protocol) server that provides comprehensive integration with Things3 on macOS. This server enables AI assistants and other MCP clients to interact with Things3 through 25 specialized tools, offering complete task management capabilities with intelligent error correction and automatic tag creation.
Features
- **Complete Things3 Integration**: 25 tools covering all aspects of Things3
- **TODO Management**: Create, read, update, delete, complete, and uncomplete tasks
- **Project & Area Management**: Full project lifecycle support with area organization and deletion
- **Tag System**: Hierarchical tag support with creation, deletion, and bulk tag operations
- **Bulk Operations**: Efficiently move or update multiple items at once
- **Automatic Tag Creation**: Tags are automatically created when referenced in TODO/project operations
- **Error Correction**: Automatic fixing of common issues (date conflicts, missing titles)
- **Logbook Search**: Search completed items with date range filtering
- **Performance Optimized**: Connection pooling and AppleScript optimization
Requirements
- **macOS** (Things3 is macOS-only)
- **Node.js** >= 16.0.0
- **Things3** app installed
- **AppleScript** access enabled in System Settings
Installation
Quick Start (Recommended)
You can use the server without any installation:
Install from npm
Then add to your MCP client configuration:
Install from Source
Configuration
Environment Variables
For update operations (modify, complete, delete), you need to set your Things3 authorization token:
To find your authorization token:
1. Open Things3
2. Go to Settings → General
3. Click "Enable Things URLs"
4. Click "Manage"
5. Copy the authorization token value
You can also create a .env file (see .env.example).
For Claude Desktop
1. Open Claude Desktop configuration:
- **macOS**: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Add the Things3 MCP server using one of these methods:
**Method 1: Using npx (easiest, no installation required)**
**Method 2: Global npm install**
**Method 3: Local installation**
3. Restart Claude Desktop
For Other MCP Clients
Use any of the methods above, adapting the configuration to your MCP client's format.
Available Tools
TODO Tools (7)
todos_list
List TODOs with flexible filtering options.
**Parameters:**
- filter: "inbox" | "today" | "upcoming" | "anytime" | "someday" | "logbook" (optional)
- searchText: Search within titles and notes (optional)
**Example:**
todos_get
Get detailed information about a specific TODO.
**Parameters:**
- id: The TODO's unique identifier (required)
todos_create
Create a new TODO with full property support (automatically creates tags if they don't exist).
**Parameters:**
- title: Task title (required)
- notes: Additional notes (optional)
- whenDate: ISO 8601 date string for scheduling (optional)
- deadline: ISO 8601 date string for due date (optional)
- tags: Array of tag names (optional)
- checklistItems: Array of checklist item titles (optional) *
- projectId: Assign to project (optional)
- areaId: Assign to area (optional)
- heading: Title of heading within project to add to (optional)
**Example:**
\* **Note on Checklists**: When checklistItems are provided, the TODO is created using Things3's URL scheme instead of AppleScript. This approach has some limitations:
- Things3 may briefly come to the foreground
- The created TODO's ID cannot be directly retrieved, so the server searches for it by title
- If multiple TODOs have identical titles, the wrong TODO might be returned
- URL scheme support must be enabled in Things3 settings (Settings → General → Enable Things URLs)
todos_update
Update an existing TODO's properties (automatically creates tags if they don't exist).