things3-mcp-server
This server provides an MCP interface to interact with the Things 3 macOS app via AppleScript, enabling an AI agent to read and manage tasks, projects, areas, and tags.
Read to-dos: Retrieve to-dos from Today, Inbox, or recently completed (Logbook) with a configurable look-back period. List to-dos within specific lists, areas, or projects, with status filtering (open, completed, canceled). Search by name substring and fetch single to-dos by ID.
Read structure: List all areas, projects (optionally filtered by area), and tag names.
Create to-dos: Create new to-dos with optional notes, area/project assignment, tags, scheduled date (
when), and deadline.Manage to-dos: Complete or cancel to-dos (cancel is reversible). Update to-dos by replacing or appending tags, rescheduling, changing deadline, or moving to another built-in list. Target to-dos by unique ID or name query, with support for exact matching.
Safety & integration: All commands use parameterized AppleScript to prevent injection. Requires Things 3 to be installed, running, and granted Automation permission.
Click on "Deploy 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., "@things3-mcp-server list my inbox items"
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.
things3-mcp-server
MCP server for Things 3 on macOS. Read and write to-dos, lists, areas and projects — so an agent can drive the same task workflows a human does in Things (triage Today, log completed work, file new tasks, reschedule).
Built for the KI-OS workflow: it replaces the ad-hoc AppleScript snippets used
for /review, the purchase-decision framework and the loop↔Things sync with a
proper tool surface.
How it works
All access goes through AppleScript (osascript), invoked with an
on run argv handler so user-provided values (task titles, notes, tags) are
passed as real arguments — never interpolated into the script, so there is no
injection risk. No external Python dependency beyond the MCP SDK; nothing reads
the Things SQLite database directly, which keeps writes safe and avoids schema
coupling.
Requires the Things 3 app to be installed and running. On first use macOS will ask to grant Automation permission to control Things 3 — approve it for the host process (Claude / your terminal).
Related MCP server: Things MCP
Tools
Tool | Kind | Purpose |
| read | To-dos in a list / area / project |
| read | Everything in the Today list |
| read | Everything in the Inbox |
| read | Recently completed to-dos (Logbook) |
| read | Find to-dos by name substring |
| read | A single to-do by id |
| read | All areas |
| read | Projects (optionally within an area) |
| read | All tag names |
| write | Create a to-do |
| write | Complete open to-do(s) by name or id |
| write | Cancel open to-do(s) — reversible, no delete |
| write | Update the first matching open to-do |
| write | Append tags without dropping existing ones |
Write tools accept either todo_id (exact, safest — e.g. an id from
create_todo) or a name query (exact=True for an exact match instead of a
substring).
Keeping list responses small
All list-returning read tools (list_todos, get_today, get_inbox,
get_completed, search_todos) accept three shaping arguments:
arg | effect |
| keep only to-dos carrying ANY of these tags (case-insensitive) |
| drop the |
| keep at most N to-dos, applied after the tag filter |
Defaults are unchanged ("", True, 0), so existing calls behave exactly as
before.
Why this exists — measured against a real Anytime list of 87 to-dos:
list_todos("list", "Anytime") 55,952 chars
+ include_notes=False 18,085 chars (-68 %)
+ tag="48h-Liste,Spontankauf" 4,047 chars (-93 %)Two to-dos were being looked for. Notes are the bulk of the payload, and they are
worth having — just not in an overview. Fetch them per to-do with get_todo().
The tag filter is also a correctness matter, not only a size one: a purchase decision is identified by its tag, not by its area, and a to-do filed in no area at all is the normal case for something captured quickly. Filtering by area silently misses those.
Removing a deadline
update_todo(deadline="none") removes an existing deadline. An empty string
leaves it untouched — those are different operations, and the distinction matters:
Things shows a to-do in Today whenever its deadline is due or overdue, regardless of when the to-do is scheduled. Rescheduling alone therefore does not get a to-do out of Today — a stale deadline from months ago keeps pulling it back, silently, and Today stops being a list of what is actually due today.
AppleScript has no missing value for this property (due date is typed date,
so assigning missing value fails with error -1700). The tool uses
delete due date of t instead, which does work — verified against the live app in
both directions: removing yields missing value, and setting an ISO date
afterwards still works.
Todo objects carry: id, name, status, tags, due (deadline, ISO),
when (scheduled/activation date, ISO), project, area, completion (ISO),
notes. Dates are YYYY-MM-DD strings; when accepts today, tomorrow,
anytime, someday or an ISO date.
Install
cd ~/workspace/things3-mcp-server
python3 -m venv .venv
.venv/bin/pip install -e .Register with Claude Code (user scope)
claude mcp add things3 --scope user -- \
~/workspace/things3-mcp-server/.venv/bin/things3-mcp-serverDesign note
The MCP stays a generic Things wrapper. Domain semantics — e.g. the ADHS
48h purchase-decision rule (48h-Liste tag, +2 days, then Spontankauf +7) —
live in the KI-OS skills, not here. update_todo(query, tags=..., move_to_list="Anytime")
is exactly the primitive the 48h→Spontankauf transition needs.
Scope / non-goals
The interactive "Einkäufe ADHS" Shortcut is deliberately not wrapped (it needs UI dialogs and stays manual).
No delete tool by design —
cancel_todo(reversible) covers "drop this task" (e.g. a rejected purchase decision); hard deletion is intentionally left out.
Maintainer
Schimmi — https://schimmilab.de Issues und Pull Requests willkommen.
Available Tools
14 toolsadd_tagsA
Append tags to the first matching OPEN to-do WITHOUT removing existing ones.
Unlike update_todo(tags=...) which replaces the whole tag set, this merges the given tags into the current ones (duplicates skipped).
Inputs: tags (required), exact, query, todo_id. Returns: object
cancel_todoA
Mark open to-do(s) as canceled (reversible — prefer this over deleting).
Target by todo_id or query (same matching rules as complete_todo).
Useful e.g. for a rejected purchase decision. Returns canceled task names.
Inputs: exact, query, todo_id. Returns: object
complete_todoA
Mark open to-do(s) as completed.
Target by todo_id (exact, safest — e.g. an id returned from create_todo)
or by query (name match). With exact=False (default) every OPEN to-do
whose name contains query is completed; set exact=True to require an
exact name match. Returns the completed task names — check them.
Inputs: exact, query, todo_id. Returns: object
create_todoB
Create a new Things 3 to-do.
Inputs: title (required), area, tags, when, +3 more. Returns: object
get_completedA
List to-dos completed within the last days days (from the Logbook).
Useful for syncing finished tasks back into other systems. days
defaults to 30.
Inputs: tag, days, limit, include_notes. Returns: result
get_inboxA
List all to-dos currently in the Things 3 "Inbox" (unfiled tasks).
Inputs: tag, limit, include_notes. Returns: result
get_todayA
List all to-dos currently in the Things 3 "Today" list.
Inputs: tag, limit, include_notes. Returns: result
get_todoA
Get a single to-do by its Things id. Returns null if it does not exist.
Inputs: todo_id (required). Returns: result
list_areasA
List all Things 3 areas (id + name).
Inputs: no named parameters. Returns: result
list_projectsA
List Things 3 projects (id, name, status, area).
If area is given, only projects within that area are returned.
Inputs: area. Returns: result
list_tagsA
List all tag names defined in Things 3.
Inputs: no named parameters. Returns: result
list_todosB
List Things 3 to-dos within one scope.
Inputs: scope_name (required), scope_type (required), tag, limit, +2 more. Returns: result
search_todosA
Search to-dos whose name contains query (case-insensitive).
By default only open to-dos are searched; set include_completed=True to also search the Logbook.
Inputs: query (required), tag, limit, include_notes, +1 more. Returns: result
update_todoA
Update the first matching OPEN to-do (by todo_id or name query).
Inputs: tags, when, exact, query, +3 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
There are five ways to retrieve to-do lists (list_todos, get_today, get_inbox, get_completed, search_todos), and list_todos is vague about what 'one scope' means, creating unclear boundaries. The update/complete/cancel/add_tags tools also share the same todo_id-or-query targeting pattern, which could lead an agent to pick the wrong mutating operation without careful reading.
Names uniformly use lowercase verb_noun patterns: list_*, get_*, search_*, create_*, update_*, complete_*, cancel_*, add_tags. The main deviation is that get_* mixes single-item lookup (get_todo) with list-returning operations (get_today, get_completed, get_inbox), so the verb prefix does not strictly predict the return shape, but the overall style is predictable.
14 tools is reasonable for a Things 3 server and stays within the expected range, covering to-do read/write plus area/project/tag lookup. The count is slightly inflated by the many overlapping read/list routes for to-dos, but each still has a concrete intended use.
The to-do lifecycle is well covered: create, read/list/search, update, complete, cancel, and tag management are all present. The main gaps are a lack of direct deletion (mitigated by cancel_todo) and write support for projects/areas/tags, but these are reasonable for a to-do-focused server.
Maintenance
Related MCP Connectors
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Read and manage To-do Calendar todos, schedules and tags from an AI agent.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
AI-powered to-do list: add, list, complete and organise tasks across lists from any assistant.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to interact with Things 3 task manager on macOS via AppleScript, allowing users to list and create todos across different lists through natural language.20 npmMIT
- FlicenseBqualityDmaintenanceEnables Claude to interact with Things 3 on macOS, allowing users to create, update, and manage to-dos and projects, list tasks, search items, and navigate through Things lists using natural language.2016-
- AlicenseBqualityDmaintenanceEnables Claude to interact with Things 3 task management, allowing creation, analysis, and management of tasks, projects, and tags via natural language.22MIT
- AlicenseBqualityDmaintenanceEnables Claude to interact with Things 3 task management, allowing natural language task creation, project analysis, and GTD workflow automation.2473 PyPI44MIT