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 Show my tasks for today"
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 server for Things 3 on macOS. It lets Claude (Claude Code and Claude Desktop) read and write your tasks.
How it works — the reliable combination:
Operation | Mechanism | Why |
Reads (todos, projects, areas, tags, search) | Read-only SQLite via | Fast, complete, works on large libraries. Read-only cannot corrupt the database. |
Writes (create / update / complete) | Official | Cultured Code's sanctioned write path. Never touches the DB directly. |
This split is deliberate: Things' own guidance warns that writing to its database can cause data loss, so this server never does. Reads open the DB read-only; every mutation goes through the URL scheme.
Reads have two backends. By default the server auto-selects: SQLite if it can reach the database (Full Disk Access granted), otherwise AppleScript.
SQLite (default when FDA granted) | AppleScript (fallback) | |
Full Disk Access | Required | Not needed (uses Automation permission, auto-prompted) |
Things must be running | No | Yes |
Speed | Instant | Fast for most views; a few seconds for large all-todo lists |
Field coverage | Complete | Core fields (no checklist items, no per-item project/area) |
Why this matters for Claude Desktop: granting Full Disk Access to Claude.app does not always propagate to the process it spawns, so SQLite can stay blocked. The AppleScript backend sidesteps that entirely — set THINGS_MCP_BACKEND=applescript (below) and you only need the one-click Automation prompt.
THINGS_MCP_BACKEND — auto (default) · sqlite · applescript.
THINGS_AUTH_TOKEN — the Things URL token for updates/complete/cancel. Only needed on the AppleScript backend (where the token can't be read from the DB). Copy it from Things → Settings → General → Enable Things URLs → Manage.
THINGSDB — override the database path (rarely needed; it's auto-discovered).
Related MCP server: Things MCP
macOS (Things is Mac/iOS only; this server must run on the same Mac as Things).
Things 3, opened at least once so its database exists.
Python ≥ 3.11 and uv.
The Things database lives in a macOS-protected container. Without Full Disk Access, macOS blocks all reads with Operation not permitted — and naive servers silently report "no tasks found" instead of explaining why.
Grant it to the app that launches this server:
Claude Code → your terminal app (Terminal, iTerm2, etc.).
Claude Desktop → Claude.app.
System Settings → Privacy & Security → Full Disk Access → enable that app, then fully quit and reopen it.
Things → Settings → General → Enable Things URLs. This lets the server create and update items, and provides the auth token (read automatically — you never paste it).
No clone required — uv builds and runs it straight from GitHub.
claude mcp add -s user things -- uvx --from git+https://github.com/than/things-mcp things-mcp(-s user makes it available in every project. Drop it to scope the server to the current project only.)
Recommended: the AppleScript backend — no Full Disk Access needed, just one Automation click. (On Desktop, Full Disk Access granted to Claude.app often does not reach the process it spawns, so SQLite can stay blocked.)
Copy your token: Things → Settings → General → Enable Things URLs → Manage → copy the token.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add the things server (paste your token):
{
"mcpServers": {
"things": {
"command": "uvx",
"args": ["--from", "git+https://github.com/than/things-mcp", "things-mcp"],
"env": {
"THINGS_MCP_BACKEND": "applescript",
"THINGS_AUTH_TOKEN": "paste-token-here"
}
}
}
}Quit Claude Desktop (⌘Q) and reopen.
Ask it "show my Things today" → click Allow on the "uvx wants to control Things" prompt.
Prefer fast SQLite instead? Drop the env block, grant Full Disk Access to Claude.app (and, if reads still fail, to the uvx/interpreter binary), then relaunch.
If you've cloned the repo and want to run your working copy:
claude mcp add -s user things -- uv run --directory /ABSOLUTE/PATH/things-mcp things-mcpAsk Claude to run the doctor tool. All three checks should pass:
database_found — the Things DB was located.
database_readable — Full Disk Access is granted (no TCC block).
things_urls_enabled — the auth token is available.
Any failure comes with the exact fix.
Tool | Description |
| To-dos in the Inbox |
| To-dos scheduled for Today (plus overdue) |
| Scheduled future to-dos |
| To-dos in Anytime |
| To-dos in Someday |
| Completed / canceled to-dos |
| To-dos filtered by project / area / tag / status / deadline |
| Projects (optionally by area) |
| All areas |
| All tag titles |
| Search to-dos/projects by title and notes |
| Fetch one item by uuid (with checklist items) |
| Items created within an offset like |
Tool | Description |
| Create a to-do (title, notes, when, deadline, tags, checklist, list, heading) |
| Create a project, optionally pre-filled with to-dos |
| Update a to-do by id |
| Update a project by id |
| Mark a to-do complete |
| Mark a to-do canceled |
Tool | Description |
| Preflight: DB found? readable (Full Disk Access)? Things URLs enabled? |
Creating areas or tags isn't supported — the URL scheme can't create them (only AppleScript can). Areas and tags are read-only; you can apply existing tags when adding/updating.
Write confirmation is best-effort. The URL scheme doesn't return the new item's ID, so after an add the server reads the list back and tries to match by title. If it can't confirm, it says so rather than inventing an ID.
macOS only, by nature.
uv sync
uv run pytest # full suite runs against a vendored fixture DB — no live Things neededRead tests run against a Things-schema fixture database vendored from things.py (see tests/fixtures/README.md).
Reading is powered by things.py (MIT).
Built against Cultured Code's official docs: URL scheme, JSON command, AppleScript, AI tools & safe integration.
MIT — see LICENSE.
Create a project, optionally pre-filled with to-dos.
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | ||
| tags | No | ||
| when | No | ||
| notes | No | ||
| title | Yes | ||
| todos | No | ||
| deadline | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It merely states 'Create' but does not disclose behavioral traits such as whether it can overwrite existing projects, authentication needs, or side effects. Significant gaps remain.
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?
The description is a single sentence with no waste, but it is too short to be effective for a tool with 7 parameters. It could be expanded to cover more details without losing conciseness.
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?
The tool has 7 parameters, no output schema, and no annotations. The description only mentions creation and optional to-dos, ignoring return values, side effects, parameter details, and prerequisites. It is severely incomplete.
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?
Schema description coverage is 0%, but the description only clarifies the 'todos' parameter (pre-filled). Other parameters like area, tags, when, notes, and deadline are left unexplained, adding minimal semantic value beyond their names.
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?
The description uses a specific verb ('Create') and resource ('project'), and adds the optional pre-fill with to-dos, which distinguishes it from siblings like update_project and add_todo. However, it could be more explicit about what constitutes a project.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use, or comparisons to siblings like update_project or add_todo.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a to-do. when: today/tomorrow/evening/anytime/someday/yyyy-mm-dd.
| Name | Required | Description | Default |
|---|---|---|---|
| list | No | ||
| tags | No | ||
| when | No | ||
| notes | No | ||
| title | Yes | ||
| heading | No | ||
| deadline | No | ||
| checklist_items | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behaviors. It only mentions creation but omits details like required authentication, side effects, or rate limits. The partial explanation of the 'when' parameter is a minor positive.
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?
The description is very short (two sentences) with no wasted words, but it is not well-structured. Critical information about other parameters is missing, prioritizing brevity over completeness.
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?
Given 8 parameters and no output schema, the description is grossly incomplete. It fails to explain most parameters, return values, or usage scenarios, leaving the agent underinformed.
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?
Schema coverage is 0% for 8 parameters. The description explains only the 'when' parameter's allowed values, leaving all other parameters (e.g., title, tags, notes) undocumented. This insufficiently compensates for the lack of schema descriptions.
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?
The description clearly states 'Create a to-do,' which specifies the verb and resource. However, it does not differentiate from sibling tools like 'add_project' or 'update_project'.
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?
No guidance is provided on when to use this tool versus alternatives such as 'list_recent' or 'cancel_todo'. The description lacks context for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a to-do canceled.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It only says 'mark canceled' without explaining whether this deletes the item, if it's reversible, or other side effects. Vague behavioral disclosure.
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?
A single short sentence with no unnecessary words. Very concise, though slightly under-specified. Lacks front-loading of key constraints.
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?
Given low complexity (one required param, no output schema) and no annotations, the description provides minimal context. It does not explain the effect of cancellation or response behavior, leaving gaps.
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?
Schema description coverage is 0%, and the description does not mention the required 'id' parameter. No added meaning beyond the bare schema, leaving the agent without clarity on what the parameter represents.
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?
The description 'Mark a to-do canceled' clearly states the verb and resource, making the action obvious. However, it does not differentiate from sibling tools like update_project or add_todo, preventing a top score.
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?
No guidance on when to use cancel_todo versus alternatives, no exclusions, and no context provided. The description implies usage only via the verb, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preflight: DB found? readable (Full Disk Access)? Things URLs enabled?
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lists the checks performed but does not disclose behavioral aspects such as side effects (likely none), error handling, output format, or required permissions. With no annotations, the description carries full burden and falls short.
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?
The description is extremely concise, using a single line with bullet-style check items. It is front-loaded with 'Preflight:' but could be phrased more clearly. It earns its space but sacrifices clarity.
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?
Given no output schema or annotations, the description should explain what the tool returns or how to interpret results. It only lists checks, omitting whether it returns success/failure, a report, or throws on failure. This is insufficient for effective use.
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?
The tool has no parameters, so schema description coverage is 100% vacuously. The description adds meaning by naming the checks, which is adequate. Per guidelines, a baseline of 4 is appropriate for zero parameters.
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?
The description 'Preflight: DB found? readable (Full Disk Access)? Things URLs enabled?' clearly indicates a health check tool that verifies database accessibility, permissions, and URL configuration. It distinguishes from sibling CRUD tools (e.g., add_todo, get_item) by being a diagnostic utility.
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?
No guidance is provided on when to use this tool versus alternatives. It does not specify prerequisites, typical contexts (e.g., before other operations), or when it should be avoided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single to-do/project/area by uuid (with checklist items).
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only mentions fetching with checklist items. Does not disclose read-only nature, authentication needs, rate limits, or behavior on missing UUID. For a tool with no annotations, the description should provide more context.
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?
Single sentence front-loading the key information. Efficient but could include more detail without becoming verbose.
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 is simple but lacks description of return value shape (other than checklist items) and error cases. Without output schema, description should cover more edge cases.
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?
Schema has 0% coverage for parameter descriptions. The description only says 'by uuid' without detailing format, length, or pattern. Adds minimal meaning beyond schema.
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?
Clearly states verb 'Fetch', resource 'to-do/project/area', and method 'by uuid'. Additionally specifies that checklist items are included, distinguishing from siblings like list_recent or cancel_todo.
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?
Implies use when needing a single item by UUID, but no explicit guidance on when not to use (e.g., for multiple items use list_recent) or alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
To-dos in the Inbox.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided and description lacks behavioral details such as read-only status, pagination, or behavior when inbox is empty. The minimal description does not compensate for missing annotations.
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?
Description is extremely concise, but is a fragment. Could be improved to a full sentence. However, given no parameters and simple purpose, it is acceptable but not exemplary.
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?
Minimal description fails to explain what 'Inbox' means or what the return format is. With no output schema and simple structure, more context is needed for complete understanding.
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?
Schema has 0 parameters, so baseline is 4. Description does not need to add parameter information. It correctly implies no arguments needed.
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?
The description 'To-dos in the Inbox.' conveys the purpose but uses a noun phrase instead of a verb-object structure. It distinguishes from siblings like list_recent by specifying the inbox scope, but is somewhat vague.
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?
No guidance on when to use this tool versus alternatives such as list_recent or other todo-related tools. Lacks context for appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Items created within an offset like '3d', '1w', '1y'.
| Name | Required | Description | Default |
|---|---|---|---|
| offset | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It only mentions returning items within a time offset, but does not state if it is read-only, whether there are limits, ordering, or pagination. The behavioral scope is minimal.
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?
The description is very concise (one sentence), but it could be more structured and informative. It is not front-loaded with the key action; the sentence structure is acceptable but not optimal. It wastes no words but lacks clarity.
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?
Given the simplicity (1 param, no output schema), the description is somewhat complete but fails to clarify what 'items' refers to. Sibling tools indicate different item types, but without context, the agent may misuse the tool. More context (e.g., returns recent todos or projects) is needed.
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?
The input schema has 0% description coverage, so the description adds value by giving examples like '3d', '1w', '1y'. However, it does not specify the exact format or supported units, leaving some ambiguity. It partially compensates for the schema gap.
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?
The description states 'Items created within an offset' which implies listing items, but does not specify what type of items (tasks, projects, etc.). The sibling tools like list_inbox suggest different item types, but the description does not distinguish. It is clear but lacks specificity.
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?
No guidance is provided on when to use this tool versus alternatives like list_inbox. There is no mention of when-not-to-use or prerequisites. The description only states what it does, not the context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing project by id (requires Things URLs enabled).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| tags | No | ||
| when | No | ||
| notes | No | ||
| title | No | ||
| canceled | No | ||
| deadline | No | ||
| completed | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. Only says 'update', implying mutation, but does not mention side effects, error handling (e.g., missing id), or authorization needs.
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?
Extremely short, but lacks essential information. Under-specification outweighs brevity; fails to provide value.
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?
With 8 parameters, no output schema, and no annotations, the description leaves most behavioral and parameter details unspecified, making the tool hard to use correctly.
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?
Schema coverage is 0% and description does not explain any parameter. The agent cannot infer the meaning of tags, when, notes, etc., beyond their names.
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?
The description states 'Update an existing project by id', which clearly identifies the verb and resource. It distinguishes from siblings like add_project (creation) but includes an unclear prerequisite 'requires Things URLs enabled'.
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?
No guidance on when to use this tool versus alternatives like add_project for creation or cancel_todo for tasks. Missing context on appropriate scenarios.
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_todocancel_tododoctorget_itemlist_inboxlist_recentupdate_projectEach tool targets a distinct aspect—list_recent for time-based retrieval, list_inbox for inbox, get_item for individual items, cancel_todo for state change, add_todo/add_project for creation, update_project for project updates, and doctor for diagnostics—no overlap in purpose.
Most tools follow a verb_noun pattern (list_recent, cancel_todo, add_todo, etc.), but 'doctor' is a noun and breaks the convention, creating a minor inconsistency.
With 8 tools, the server covers core operations for a task management system without being overwhelming; each tool serves a clear role.
Missing some lifecycle operations: no way to delete items, update to-dos beyond canceling, or list all projects explicitly. Core create/read/cancel is covered, but update and delete are limited.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/than/things-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
