things3-mcp

# MCP Server for Things3 A robust MCP (Model Context Protocol) server providing comprehensive integration with Things3, allowing you to create, manage, and search tasks and projects through the MCP protocol. Features ID-based task management, JSON-based AppleScript integration, and Things3 philosophy guidance. ## Features - ✅ **Create Projects & Todos**: Full metadata support with checklists, tags, and dates - ✅ **Update Tasks**: Modify any task property using task IDs with auth token support - ✅ **View Tasks**: List tasks from Inbox, Today, Upcoming, Anytime, or Projects - ✅ **Complete Tasks**: Mark todos as completed using their ID - ✅ **Search Functionality**: Search through all todos by title or content - ✅ **Things3 Philosophy**: Built-in guidance for effective task management - ✅ **JSON Integration**: Reliable data extraction using Foundation framework - ✅ **Today Overload Warning**: Alerts when Today list exceeds 4 items ## Installation ### Prerequisites - macOS with Things3 installed - Python 3.10+ - Things3 running (for real-time operations) - Things3 auth token (for update operations) ### Install the Server 1. Clone this repository: ```bash git clone <repository-url> cd mcp-things3 ``` 2. Install using pip: ```bash pip install -e . ``` 3. The server will be available as `mcp-server-things3` ### Auth Token Setup For update operations, you need to set your Things3 auth token: 1. Open Things3 2. Go to Settings → General → Enable Things URLs → Manage 3. Copy your auth token 4. Set the environment variable: ```bash export THINGS3_AUTH_TOKEN="your-token-here" ``` ## Tools Available ### View Operations #### `view-inbox` View all todos in the Things3 inbox. - **Parameters**: None - **Returns**: List of inbox todos with IDs, titles, tags, and metadata #### `view-todos` View all todos in today's list with overload warning. - **Parameters**: None - **Returns**: List of today's todos with IDs and warning if >4 items ###…