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.
- ✅ 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
- 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
No installation required! Use directly with:
npx things-mcpnpm install -g things-mcpAdd the server to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Using npx (recommended):
{
"mcpServers": {
"things": {
"command": "npx",
"args": ["-y", "things-mcp"]
}
}
}Using global installation:
{
"mcpServers": {
"things": {
"command": "things-mcp"
}
}
}Once configured, you can interact with Things through your MCP client using natural language. Here are some examples:
"Create a todo to buy groceries for tonight"
"Add a todo 'Call dentist' with a deadline of next Friday"
"Create multiple todos: milk, bread, eggs in my Shopping project"
"Create a project called 'Website Redesign' in my Work area"
"Make a project 'Vacation Planning' with todos: book flights, reserve hotel, research activities"
"Update my 'Call dentist' todo to be due tomorrow"
"Add notes to my website project about the new color scheme"
"Mark the groceries todo as completed"
"Show my Today list"
"Search for all todos tagged with 'urgent'"
"Open the Someday list filtered by work tags"
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
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
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
- duplicate - Create copy before updating
Modify existing projects with similar options to update command.
Navigate to specific items or lists:
- id - Specific item ID or built-in list (inbox, today, anytime, etc.)
- query - Search by name
- filter - Filter by tags
Search across all Things data:
- query - Search terms
Advanced batch operations using JSON format for complex project structures.
Get Things app and URL scheme version information.
Some operations (updates) require an authorization token from Things:
- macOS: Things → Settings → General → Enable Things URLs → Manage
- iOS: Settings → General → Things URLs
Copy your unique token and use it with update operations.
To update specific items, you need their IDs:
- Control-click on todo/project → Share → Copy Link
- Control-click on list in sidebar → Share → Copy Link
- Tap todo/project → toolbar → Share → Copy Link
- Navigate to list → top right → Share → Copy Link
The server includes comprehensive error handling:
- Invalid parameters are caught by Zod validation
- Things URL failures are reported with clear messages
- Missing authorization tokens are detected
- Network and system errors are handled gracefully
// Creates a simple todo
{
"title": "Buy milk",
"when": "today",
"tags": ["groceries"]
}// Creates a project with multiple todos and organization
{
"title": "Plan Birthday Party",
"area": "Personal",
"when": "next week",
"to-dos": [
"Send invitations",
"Order cake",
"Buy decorations",
"Plan menu"
],
"tags": ["family", "celebration"],
"reveal": true
}// Complex structure with headings and nested todos
{
"data": JSON.stringify([
{
"type": "project",
"attributes": {
"title": "Website Redesign",
"area": "Work",
"items": [
{
"type": "heading",
"attributes": { "title": "Design Phase" }
},
{
"type": "to-do",
"attributes": {
"title": "Create wireframes",
"when": "today"
}
}
]
}
}
])
}- Ensure Things 3 is installed and updated
- Check that Things URLs are enabled in settings
- Verify the MCP server is running correctly
- Get your auth token from Things settings
- Include auth-token parameter for update operations
- Ensure token is copied correctly without extra spaces
- Restart Claude Desktop or your MCP client
- Check the configuration file syntax
- Look for errors in client logs
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Submit a pull request
MIT License - see LICENSE file for details.
- 🐛 Bug Reports: Open an issue on GitHub
- 💡 Feature Requests: Open an issue with enhancement label
- 📚 Documentation: Check the Things URL scheme docs
- 💬 Questions: Open a discussion on GitHub