Things 3 MCP Connector
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Things 3 MCP Connector
A hosted OAuth remote Model Context Protocol (MCP) connector for Cultured Code's Things 3, deployed on Cloudflare Workers (things3mcp.org).
This connector talks directly to Things Cloud using its native wire format (Task6, Area3, Tag4, ChecklistItem3, schema 301) to read tasks and commit changes atomically via Things Cloud sync.
Features
Full Things JSON Specification: Complete compatibility with Cultured Code's Things JSON format (
things:///json).Batch create projects, sections/headings, to-dos, checklist items, and tags in a single atomic commit.
Honors all standard attributes:
completed,canceled,completion-date,creation-date,when,deadline,reminder-time,area-id,area,list-id,list,heading-id,heading, andtags.Dynamic container resolution:
list-idandlistautomatically resolve to projects or areas. To-dos assigned to a container default to"anytime"scheduling rather than landing in the Inbox.Update operations: Full support for
"operation": "update"with"id"on to-dos and projects. Applies only specified fields and rejects non-existent IDs with an error without creating unwanted items.Operation reporting: Clear per-item status (
createdvsupdated) in results.
Date & Status Handling:
Sets
creation_dateandcompletion_datevia ISO 8601 strings (e.g.,2026-08-31T17:00:00Zor2026-08-31).Follows Things' rules: completion dates only apply to completed (
ss: 3) or canceled (ss: 2) items (reset to null on open items), and neither creation date nor completion date can be in the future.Supports all scheduling targets:
inbox,today,tomorrow,evening,anytime,someday, or calendar datesYYYY-MM-DD.
Bulk Operations:
things_batch_update_todos: Batch complete, cancel, trash, reschedule, or set dates (completion_date,creation_date,deadline) across multiple to-dos simultaneously.things_import_json: Atomic multi-entity import and update in a single sync transaction.
Incremental Cached Sync: Fast in-memory state with 15-second cache TTL, 429 rate limit backoff, and automatic pagination handling.
Security & OAuth: Cloudflare Workers OAuth 2.0 provider integration. Things credentials are stored once, inside the grant, encrypted with AES-256-GCM under a key derived from the
DATA_ENCRYPTION_KEYsecret with HKDF-SHA-256 (see Behavior Notes).
Related MCP server: things-mcp
Tool Reference
Import & Bulk Operations
things_import_json: Import or update complex structured projects, headings, to-dos, checklists, and tags using Things JSON format in a single atomic sync commit.things_import_csv: Import tasks into Things 3 from CSV exports (supports Asana, Todoist, OmniFocus, and standard spreadsheet formats) with automatic mapping of titles, notes, due dates, creation dates, completion dates, and project/area assignment.things_batch_update_todos: Perform batch operations (complete,cancel,trash,reschedule,set_dates) across multiple to-do UUIDs. A field the operation does not use is an error.things_batch_update_projects: Perform batch operations (complete,cancel,trash,reschedule,set_area,set_dates) across multiple project UUIDs. A field the operation does not use is an error.
To-Dos & Checklists
things_add_todo: Create a new to-do with scheduling, reminder alert, deadline, container, checklist, and dates. Therepeatoption creates a repeating to-do (see Behavior Notes).things_update_repeat: Edit the rule of a repeating to-do, pause it, resume it, or stop it (see Behavior Notes).things_update_todo: Update any property of an existing to-do, includingcompletion_date,creation_date, status, notes, scheduling, and tags.things_get_todo: Fetch complete details of a specific to-do by UUID or exact title.things_complete_todo: Mark a to-do as completed.things_cancel_todo: Mark a to-do as canceled.things_delete_todo: Move a to-do to Trash or permanently purge it. Only to-do ids are accepted.things_duplicate_todo: Duplicate an existing to-do, including the checked state of its checklist.things_move_todo: Move a to-do to a different schedule, project, heading, or area. Moving to Inbox, Anytime, or Someday clears the reminder time.things_convert_todo_to_project: Convert a to-do into a project, turning checklist items into to-dos.things_set_checklist: Atomically replace the entire checklist of a to-do with a new list of items.things_add_checklist_items: Append checklist items to a to-do.things_update_checklist_item: Mark a checklist item completed/canceled or rename it.things_delete_checklist_item: Delete a checklist item.
Projects & Headings
things_create_project: Create a new project with area, deadline, scheduling, and tags.things_update_project: Update project properties includingcompletion_date,creation_date, title, notes, area, deadline, and status. Completing or canceling a project closes its open to-dos with it (see Behavior notes).things_get_projects: List projects filtered by status (open,completed,all) and area.things_get_project: Fetch details of a project including headings, nested tasks, and completion dates.things_get_project_stats: Progress statistics across projects (velocity, completion %, overdue project counts).things_create_heading: Create a section heading inside a project.things_update_heading: Rename or permanently delete a section heading.
Lists & Views
things_get_today: Retrieve the Today list as Things shows it: start dates that have arrived, plus undated to-dos whose deadline is today or overdue. Takes an optionaltimezone.things_get_inbox: Retrieve unorganized Inbox to-dos.things_get_upcoming: Retrieve future scheduled tasks and future deadlines. Takes an optionaltimezone.things_get_anytime: Retrieve Anytime tasks filtered by area or tag.things_get_someday: Retrieve Someday tasks.things_get_logbook: Retrieve completed or canceled items sorted by completion date, with optionalsinceanduntilfiltering. A bareYYYY-MM-DDis a calendar day in the connector's time zone, or intimezonewhen given.things_get_trash: Retrieve trashed items.things_get_repeating_todos: Retrieve repeating templates with their rule in words.
Tags, Areas & Account
things_create_area/things_update_area/things_delete_area/things_get_areas: Full lifecycle management of Areas of Responsibility.things_create_tag/things_update_tag/things_delete_tag/things_get_tags/things_add_tags/things_remove_tags: Full lifecycle tag management including shortcuts and hierarchy.things_empty_trash: Permanently purge all trashed items. A trashed project or heading is purged with everything inside it.things_get_account_info: Account status, Maildrop address, and database counts. The history key is not returned.things_manage_maildrop: Get, reset, or clear the Maildrop address. Reset and clear invalidate the current address for good.things_get_daily_summary/things_get_deadlines/things_search: Daily briefing, deadline overview, and search (trashed items, headings, and repeating templates are not searched). The first two take an optionaltimezone.things_export_markdown: Export an entire project or Inbox to formatted Markdown.things_get_deep_link: Generate athings:///show?id=...URL.
Prompts & Workflow Guides
daily-planning: Interactive planning session reviewing today's agenda, upcoming deadlines, and inbox triage.weekly-review: Complete Getting Things Done (GTD) weekly review routine.project-breakdown: Decompose milestone goals into structured projects with headings, actions, and checklists.asana-migration-audit: Step-by-step guidance and verification for migrating from Asana to Things 3.
Behavior Notes
Each tool accepts only its own kind of item. To-do tools refuse project and heading ids, project tools refuse to-do ids, and the permanent-delete tools refuse any id that is not the kind they name. Giving
things_delete_checklist_itemthe parent to-do's id deletes nothing.Dates must exist.
2027-02-31is an error, not March 3.A reminder needs a date.
reminder_timewith nowhenschedules the to-do for today; withinbox,anytime, orsomedayit is refused. Moving a to-do to one of those lists clears its reminder.nullor""removes a reminder or a deadline. A reminder at exactly 00:00 cannot be stored.Project plus heading. When both are given, the heading must belong to that project and the to-do is filed under it. A heading of another project is refused.
Today lists open to-dos whose start date is today or earlier (including scheduled to-dos the Things apps have not yet moved into Today) and to-dos with no start date whose deadline is today or overdue. To-dos inside a trashed, completed, or canceled project are not listed as live anywhere.
Closing a project closes its to-dos. As in the Things app, completing a project completes every open to-do in it, including those under its headings, and canceling it cancels them. This happens in the same commit, with the project's completion date, through
things_update_project,things_batch_update_projects, and athings_import_jsonupdate, and the result says how many to-dos were closed. To-dos that are already completed, canceled, or trashed, headings, and repeating templates are not touched. Reopening a project does not reopen its to-dos.Importing a finished project. When
things_import_jsoncreates a project as completed or canceled, the to-dos created in it, including those under its headings, are created with the project's status and completion date unless they carry a completed or canceled status of their own. The result gives the count astodosClosedWithProjectand astodosClosedon the project. A new open to-do filed into a project that was already completed or canceled is still refused.Repeating to-dos. A template is returned with
"repeating": true,"when": "repeating","repeatRule"(for example "Every week on Monday") and a"repeat"object (frequency, interval, mode, next occurrence, end, deadline offset, andpaused, which istruewhile the repeat is paused). Itsdeadlineisnull; a template with deadlines turned on says so in the rule. Templates are left out of lists, search, and project counts;things_get_projectreturns them separately asrepeatingTemplates. The to-dos a template generates carry"repeatTemplateId".Creating a repeating to-do.
things_add_todotakes arepeatobject and writes one hidden template; the Things apps generate the to-dos from it. Supported rules are the ones recorded from the Things app: daily and every N days; weekly on chosen weekdays, every N weeks; monthly on day(s) of the month, on the last day, or on the 1st to 4th or last weekday; yearly on a date or on the 1st to 4th weekday of a month; after completion every N days; ending never, on a date, or after N times. Anything else is refused with a message that lists these (no deadlines or reminder times on a repeat, no weekly, monthly, or yearly after-completion rule).repeat.startsis the first day and defaults to the next day the rule falls on, counting today. A given start must be a day the rule falls on and not in the past.whenmay be left out or name the same first day (today,tomorrow, or a date); any otherwhen, or awhenthat disagrees withrepeat.starts, is refused.Editing, pausing, and stopping a repeat.
things_update_repeattakes the template id, or the id of one of its occurrences, and oneaction. Each action writes only what Things 3.24.2 was recorded writing for it, and refuses anything else.rulereplaces the rule with arepeatobject (the same options asthings_add_todo). If the new rule falls on the repeat's current next day, only the rule is written and the next day stays where it is. If it does not, the next day moves to the first day on or after it that the new rule falls on, and never to a day before today.repeat.startsmay name the new next day instead: it must be on or after the current next day, not in the past, and a day the rule falls on. The result gives the next day and says whether it moved. Also refused: a paused repeat (resume it first), a rule that repeats after completion on either side of the edit, and a repeat with a deadline offset.pauseandresumeswitch the creation of new occurrences off and on. Pausing a paused repeat writes nothing.stopends the repeat in one commit: the template is deleted, every open occurrence becomes an ordinary to-do, and a plain to-do is created for the next day with the template's title, notes, tags, checklist items (each keeping its status), and project, heading, or area. Completed, canceled, and trashed occurrences are left alone. Stop is refused when the template is paused, adds deadlines or reminders, or has a next day that is not in the future. Trashing the template withthings_delete_todoalso ends a repeat and is the alternative in those cases.
Filters (
area,project,tag) take an id or a title, case-insensitively. An unknown name is an error, not an empty list.Tags have unique titles and cannot be nested in a cycle. A tag title with spaces is fine in Things; the owner's sync app matches it to its Apple Reminders hashtag with the spaces removed.
things_import_jsonupdates.checklist-itemsreplaces the checklist,append-checklist-itemsadds to it,add-tagsadds tags, and two updates for the same id are merged into one change.things_import_csvfiles rows into projects, areas, and headings that already exist. It creates to-dos only.Login pages escape every value they show and are served with a Content-Security-Policy that allows no scripts.
Concurrent edits. When Things Cloud rejects a commit because another device committed first, the connector syncs and tries again. Anything it computed from the old state is computed again from the new one before the retry: the full tag list of an item when a tag is added, removed, or deleted, the position of new checklist items, the checklist being replaced, the open to-dos of a project being closed, the contents of an area being deleted or a Trash being emptied, appended notes, and a whole
things_import_jsonplan. A tag another device added in between is therefore kept. A plain field change (a new title, for example) is resent as it was. New items keep the same ids across retries, so a retry cannot create a duplicate. If the rebuilt change is no longer possible (the item was deleted in between), the call fails and nothing is written. Emptying the Trash after a conflict purges only what was in the Trash when the tool was called and is still there.Batch fields. Each batch operation takes only its own fields, and any other field is an error that names it, with nothing written. For to-dos:
completeandcanceltakecompletion_date;trashtakes none;rescheduletakeswhen;set_datestakesdeadline,completion_date,creation_date. Projects are the same, plusset_areawitharea, andset_datesalso takeswhenandarea.Closed projects. A new open to-do cannot be filed into a completed or canceled project, or under one of its headings: it would be hidden in the Logbook with the project. The error names the project. A to-do created as completed or canceled is accepted there, so finished work can be imported into a finished project. Importing a completed project together with open to-dos inside it is refused for the same reason.
Time zone. "Today" is the calendar day in
USER_TIMEZONE(America/New_York).things_get_today,things_get_upcoming,things_get_deadlines,things_get_daily_summary, andthings_get_logbooktake an optionaltimezone(an IANA name such asEurope/Paris; an unknown name is an error) to answer for another zone in that one call. Writes always use the configured zone:when: "today"means today inUSER_TIMEZONE.Stored credentials. The Things email and password are stored once, encrypted, in the OAuth grant. The provider deletes them with the grant when it is revoked, and when a new sign-in by the same user and client replaces it. The key is derived from
DATA_ENCRYPTION_KEYwith HKDF-SHA-256. Records written with the earlier key (the first 32 characters of the secret) still open, and are re-encrypted the next time the grant gets a token. Grants made before 2026-11-09 also kept a copy in a per-grant Durable Object; that copy is deleted the next time the grant gets a token. The sign-in form checks for a pending authorization request before it sends the password to Things Cloud.
Interactive list (MCP App)
In hosts that support MCP Apps (Claude on the web, desktop and mobile), things_get_today, things_get_inbox, things_get_upcoming, things_get_anytime, things_get_someday and things_get_project render a Things-styled list instead of plain JSON: title, notes snippet, project or area, tags, checklist progress, scheduled date, deadline, a "This Evening" section, project headings and a progress pie. It follows the host's light and dark theme and works inline, full screen and at phone width.
Completing a to-do: ticking a checkbox calls the existing
things_complete_todotool, only on that click. The row ticks at once and rolls back with an error line if Things Cloud refuses the change. The view calls no other tool, so nothing destructive (trash, permanent delete) is reachable from it.Other hosts: each tool still returns the same JSON text, so hosts without MCP Apps support are unaffected. The view's payload is a trimmed copy in
structuredContent(notes cut to 140 characters, at most 200 to-dos).Sandbox domain: the
ui://things3/list.htmlresource sets_meta.ui.domainto the first 32 hex characters of the SHA-256 ofhttps://things3mcp.org/mcpplus.claudemcpcontent.com. If the endpoint users add ever changes, updateCONNECTOR_BASE_URL(or the path), because the hash covers the exact URL.Glyphs and icons are original artwork: the list icons in
src/app/glyphs/come fromscripts/make-glyphs.mjsand the app icons inpublic/fromscripts/make-icons.py. They are drawn for this project and MIT licensed. Nothing here is taken from Things 3.Editing the view: the source is
src/app/things-list.html. Runnpm run build:appto inline the MCP Apps SDK client and regeneratesrc/things-list-app.generated.js(Workers have no filesystem, so the HTML ships as a string). A test fails if the generated file is stale. The view makes no network requests and declares an empty CSP allowlist.
Development & Testing
# Run test suite
npm test
# Rebuild the MCP App view after editing src/app/things-list.html
npm run build:app
# Run local development server
npm run dev
# Deploy to Cloudflare Workers
npm run deployLicense
MIT. See LICENSE.
This is an independent, unofficial project. Things is a trademark of Cultured Code GmbH & Co. KG, which does not endorse or support it.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Headless task management for bots, apps and AI agents. Remote MCP server, OAuth or access token.
Hosted MCP server with managed OAuth for 15+ toolkits: Google Workspace, Fitbit, Oura, Kalshi, etc.
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server that gives AI agents read/write access to your Things3 tasks via the Things API.321Apache 2.0
- AlicenseBqualityCmaintenanceAn MCP server for Things 3 on macOS that enables reading and writing tasks, projects, and more via Claude, using read-only SQLite and the official Things URL scheme.201MIT
- AlicenseAqualityDmaintenanceA minimal MCP server for Things 3 on macOS that enables listing projects and tasks, creating tasks, and updating task status or metadata via natural language.4MIT
- AlicenseAqualityBmaintenanceEnables MCP clients to manage Things 3 tasks locally on macOS, including searching, creating, editing, scheduling, moving, completing, and trashing tasks through supported automation interfaces.2014MIT