The Things MCP Server enables Claude Desktop to interact with your task management data in the Things app, offering comprehensive functionality for personal productivity management:
- Access standard lists: Inbox, Today, Upcoming, Anytime, Someday, Logbook, and Trash
- Manage projects and areas: Create, update, and organize your workflow structure
- Work with tags: Retrieve tagged items or get all available tags
- Search capabilities: Find tasks by title, notes, or advanced filters (status, deadline, tag, area)
- Time-based operations: View recently created items or completed todos within specific periods
- Detailed information: Access todos with checklists, projects with contained items
- Create and update: Add new todos/projects with complete details (tags, deadlines, notes, checklists) or modify existing ones
- Direct app integration: Show specific items or lists directly in the Things app
Things MCP Server
This Model Context Protocol (MCP) server lets you use Claude Desktop to interact with your task management data in Things 3 from Cultured Code. You can ask Claude to create tasks, analyze projects, help manage priorities, and more.
This server leverages the Things.py library and the Things URL Scheme.
Support the Project
If you find this project helpful, consider supporting its development:
Features
- Access to all major Things lists (Inbox, Today, Upcoming, etc.)
- Project and area management
- Tag operations
- Advanced search capabilities
- Recent items tracking
- Detailed item information including checklists
- Support for nested data (projects within areas, todos within projects)
Installation
Prerequisites
- macOS (Things 3 is Mac-only)
- A MCP client, such as Claude Desktop or Claude Code
- Things 3 app with "Enable Things URLs" turned on (Settings → General)
DXT Installation (Recommended for Claude Desktop)
Desktop Extensions (.dxt) provide the easiest way to install MCP servers.
- Download the latest
things-mcp-0.4.0.dxt
file from the releases page - Double-click the
.dxt
file to install it in Claude Desktop - The extension will be automatically configured and ready to use
That's it! The DXT package includes all Python dependencies and handles the configuration automatically.
To setup Things MCP with Cladue Code, or other MCP clients, scroll down to the Manual Installation section.
Verify it's working
After installation:
- If using Claude Desktop, you should see "Things MCP" in the "Search and tools" list
- Try asking: "What's in my Things inbox?"
Sample Usage with Claude Desktop
- "What's on my todo list today?"
- "Create a todo to pack for my beach vacation next week, include a packing checklist."
- "Evaluate my current todos using the Eisenhower matrix."
- "Help me conduct a GTD-style weekly review using Things."
Tips
- Create a project in Claude with custom instructions that explains how you use Things and organize areas, projects, tags, etc. Tell Claude what information you want included when it creates a new task (eg asking it to include relevant details in the task description might be helpful).
- Try adding another MCP server that gives Claude access to your calendar. This will let you ask Claude to block time on your calendar for specific tasks, create todos from upcoming calendar events (eg prep for a meeting), etc.
Available Tools
List Views
get-inbox
- Get todos from Inboxget-today
- Get todos due todayget-upcoming
- Get upcoming todosget-anytime
- Get todos from Anytime listget-someday
- Get todos from Someday listget-logbook
- Get completed todosget-trash
- Get trashed todos
Basic Operations
get-todos
- Get todos, optionally filtered by projectget-projects
- Get all projectsget-areas
- Get all areas
Tag Operations
get-tags
- Get all tagsget-tagged-items
- Get items with a specific tag
Search Operations
search-todos
- Simple search by title/notessearch-advanced
- Advanced search with multiple filters
Time-based Operations
get-recent
- Get recently created items
Things URL Scheme Operations
add-todo
- Create a new todoadd-project
- Create a new projectupdate-todo
- Update an existing todoupdate-project
- Update an existing projectshow-item
- Show a specific item or list in Thingssearch-items
- Search for items in Things
Tool Parameters
get-todos
project_uuid
(optional) - Filter todos by projectinclude_items
(optional, default: true) - Include checklist items
get-projects / get-areas / get-tags
include_items
(optional, default: false) - Include contained items
search-advanced
status
- Filter by status (incomplete/completed/canceled)start_date
- Filter by start date (YYYY-MM-DD)deadline
- Filter by deadline (YYYY-MM-DD)tag
- Filter by tagarea
- Filter by area UUIDtype
- Filter by item type (to-do/project/heading)
get-recent
period
- Time period (e.g., '3d', '1w', '2m', '1y')
Manual Installation
For advanced users who prefer to install from source:
Step 1: Install uv (Python package manager)
First, make sure you have Homebrew installed:
Then install uv (if not installed already):
Step 2: Clone the repository
Choose a location where you want to install Things MCP. For example, to install in your home directory:
Important: Remember this location! You'll need the full path. You can get it by running:
This will show something like: /Users/yourusername/things-mcp
Step 3: Install dependencies
Step 4: Configure Claude
For Claude Desktop:
- Open Claude Desktop
- Go to Claude → Settings → Developer → Edit Config
- Add the Things server to the
mcpServers
section:
Replace /Users/yourusername/things-mcp
with your actual path from Step 2!
- Save the file and restart Claude Desktop
For Claude Code:
In your terminal, run:
Replace /path/to/things-mcp
with your actual path from Step 2!
To make it available globally (across all projects), add -s user
:
Step 5: Verify it's working
After restarting your MCP client:
- If using Claude Desktop, you should see "Things 3" in the "Search and tools" list
- Try asking: "What's in my Things inbox?"
Troubleshooting
If it's not working:
- Make sure Things 3 is installed and has been opened at least once
- The Things database needs to exist for the server to work
- Check that "Enable Things URLs" is turned on
- Open Things → Settings → General → Enable Things URLs
- Verify the path in your configuration matches where you cloned the repository
- The path must be absolute (starting with
/
) - Run
pwd
in the things-mcp directory to get the correct path
- The path must be absolute (starting with
- Check Claude's logs for errors:
- Common issues:
- "Could not attach to MCP" - Usually means the path is wrong
- "spawn uv ENOENT" - Make sure uv was installed with Homebrew (
brew install uv
) - "No module named 'things'" - Run
uv sync
in the things-mcp directory - "Command not found: uv" - Install uv with Homebrew:
brew install uv
Updating
To update to the latest version:
Then restart Claude.
Development
Running Tests
The project includes a comprehensive unit test suite for the URL scheme and formatter modules.
Project Structure
Troubleshooting
To review the MCP logs from Claude Desktop, run this in the Terminal:
local-only server
The server can only run on the client's local machine because it depends on local resources.
Tools
Enables interaction with the Things app through Claude Desktop, allowing task creation, project analysis, and priority management using natural language commands.
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityIntegrates Claude with Todoist for natural language task management, supporting project and section organization, task creation, updating, completion, and deletion using everyday language.Last updated 6 months ago19819MIT License
- -securityFlicense-qualityLets you use Claude Desktop to interact with your task management data in Things app, enabling you to create tasks, analyze projects, manage priorities, and implement productivity workflows through natural language.Last updated 3 months ago26
- -securityFlicense-qualityA companion desktop app enabling bi-directional interaction between Claude Desktop and visual UI elements, allowing Claude to display, read from, and write to interactive interfaces while processing user events and feedback.Last updated 4 months ago56
- -securityAlicense-qualityEnables interactions with Google Cloud Tasks queues and tasks through natural language, allowing users to list, manage, pause/resume queues and handle tasks via Claude Desktop.Last updated 4 months agoMIT License