Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@things-mcp Add a todo to call the plumber tomorrow"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: Things MCP
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
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | Title of area to add to | |
| tags | No | Array of tag names | |
| when | No | When to schedule: today, tomorrow, evening, anytime, someday, date string, or date time string | |
| notes | No | Notes for the project (max 10,000 chars) | |
| title | Yes | The title of the project | |
| reveal | No | Navigate into the created project | |
| to-dos | No | Array of todo titles to create in the project | |
| area-id | No | ID of area to add to (takes precedence over area) | |
| canceled | No | Mark as canceled (takes priority over completed) | |
| deadline | No | Deadline date (YYYY-MM-DD format or natural language) | |
| completed | No | Mark as completed | |
| creation-date | No | ISO8601 date time string for creation date | |
| completion-date | No | ISO8601 date time string for completion date |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| list | No | Title of project or area to add to | |
| tags | No | Array of tag names | |
| when | No | When to schedule: today, tomorrow, evening, anytime, someday, date string, or date time string | |
| notes | No | Notes for the todo (max 10,000 chars) | |
| title | No | The title of the todo (ignored if titles is specified) | |
| reveal | No | Navigate to and show the created todo | |
| titles | No | Multiple todo titles separated by new lines | |
| heading | No | Title of heading within project | |
| list-id | No | ID of project or area to add to (takes precedence over list) | |
| canceled | No | Mark as canceled (takes priority over completed) | |
| deadline | No | Deadline date (YYYY-MM-DD format or natural language) | |
| completed | No | Mark as completed | |
| heading-id | No | ID of heading within project (takes precedence over heading) | |
| creation-date | No | ISO8601 date time string for creation date | |
| use-clipboard | No | Use clipboard content | |
| checklist-items | No | Checklist items to add (max 100) | |
| completion-date | No | ISO8601 date time string for completion date | |
| show-quick-entry | No | Show quick entry dialog instead of adding |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | JSON string containing array of todo and project objects | |
| reveal | No | Navigate to and show the first created item | |
| auth-token | No | Authorization token (required for update operations) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search query |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ID of area, project, tag, todo, or built-in list (inbox, today, anytime, upcoming, someday, logbook, tomorrow, deadlines, repeating, all-projects, logged-projects) | |
| query | No | Name of area, project, tag, or built-in list to show | |
| filter | No | Filter by tag names |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the todo to update (required) | |
| list | No | Title of project/area to move to | |
| tags | No | Replace all current tags | |
| when | No | When to schedule (cannot update repeating todos) | |
| notes | No | New notes (replaces existing, max 10,000 chars) | |
| title | No | New title (replaces existing) | |
| reveal | No | Navigate to and show the updated todo | |
| heading | No | Title of heading to move to | |
| list-id | No | ID of project/area to move to | |
| add-tags | No | Add these tags to existing ones | |
| canceled | No | Mark as canceled/incomplete | |
| deadline | No | Deadline date (cannot update repeating todos) | |
| completed | No | Mark as completed/incomplete | |
| duplicate | No | Duplicate before updating | |
| auth-token | Yes | Things URL scheme authorization token (required) | |
| heading-id | No | ID of heading to move to | |
| append-notes | No | Text to add after existing notes | |
| creation-date | No | ISO8601 date time string for creation date | |
| prepend-notes | No | Text to add before existing notes | |
| checklist-items | No | Replace all checklist items (max 100) | |
| completion-date | No | ISO8601 date time string for completion date | |
| append-checklist-items | No | Add checklist items to end | |
| prepend-checklist-items | No | Add checklist items to front |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the project to update (required) | |
| area | No | Title of area to move to | |
| tags | No | Replace all current tags | |
| when | No | When to schedule (cannot update repeating projects) | |
| notes | No | New notes (replaces existing, max 10,000 chars) | |
| title | No | New title (replaces existing) | |
| reveal | No | Navigate to and show the updated project | |
| area-id | No | ID of area to move to | |
| add-tags | No | Add these tags to existing ones | |
| canceled | No | Mark as canceled/incomplete | |
| deadline | No | Deadline date (cannot update repeating projects) | |
| completed | No | Mark as completed/incomplete | |
| duplicate | No | Duplicate before updating | |
| auth-token | Yes | Things URL scheme authorization token (required) | |
| append-notes | No | Text to add after existing notes | |
| creation-date | No | ISO8601 date time string for creation date | |
| prepend-notes | No | Text to add before existing notes | |
| completion-date | No | ISO8601 date time string for completion date |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0add-projectadd-todojsonsearchshowupdateupdate-projectversionSeveral tools have ambiguous purposes: 'update' could apply to todos or projects, while 'show' and 'search' lack clear targets. 'add-todo' and 'add-project' are distinct, but the vague verbs make selection risky.
Naming patterns are inconsistent: some tools follow verb_noun (add-todo, add-project, update-project), but 'update', 'show', 'search' are bare verbs, and 'version' and 'json' are nouns. This mix makes it hard to predict tool names.
With 8 tools, the count is within a reasonable range and not overly heavy or thin. However, the inclusion of utility tools like 'version' and 'json' suggests some bloat relative to the apparent task-management domain.
The tool surface lacks essential operations such as delete or remove for todos and projects, and 'update' is too generic to cover specific update scenarios. The 'json' and 'version' tools do not contribute to domain coverage, leaving obvious gaps in lifecycle management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
MCP server for Linear project management and issue tracking
MCP server for generating rough-draft project plans from natural-language prompts.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jimfilippou/things-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
