Skip to main content
Glama
Sign In
Things MCP

Things MCP

by mathiswrong
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Things MCP connects compatible MCP clients to the Things app on your Mac through its supported automation interfaces. Manage tasks, projects, areas and tags. Create checklists and project templates, set reminders, duplicate items and move projects with descendant summaries. The bridge runs on your Mac without a companion app or project-operated service.

IMPORTANT

Open Things 3 before launching your LLM client.

Things must already be running on the Mac hosting Things MCP before you open your AI app or browser conversation. Otherwise, you may see “unable to connect to server”. Keep Things running while you use the connection.

Already seeing the error? Open Things, fully quit and reopen your desktop client (or reload your browser client), then start a new conversation and check the connection.

Install

Your client

Setup route

Claude Desktop on macOS

Download the .mcpb extension. No Terminal or separate runtime installation.

Cowork on a Mac

Use the same desktop extension, then check the connection in a new Cowork task.

ChatGPT in a browser

Set up a private tunnel. First-time setup requires developer commands.

Other MCP clients

Configure the local transport. Setup and compatibility depend on the host.

Claude Desktop

  1. Download the .mcpb package from Releases.

  2. Open Things 3 first, then launch Claude Desktop. If the client is already open and cannot connect, fully quit and reopen it after Things is running. Open the downloaded package and select Install. The desktop client supplies the runtime; no configuration editing or Terminal commands are needed.

  3. Open Settings > Extensions > Things MCP > Configure. Enable Allow changes if you want to manage tasks, then select Save. New installations start read-only.

  4. Start a new conversation and ask: Use Things MCP to check the connection without reading or changing tasks. Allow macOS Automation access to Things if prompted.

  5. With Allow changes enabled, try: Use Things MCP to create an Inbox task called “Try Things MCP”, then read it back.

Cowork on a Mac

For Cowork on a Mac, use the same extension, start a new task, and select Cowork. Follow the Cowork installation and connection check for the steps, permission setting, and tested versions.

ChatGPT browser chats

  1. Open Things 3 on your Mac before opening ChatGPT. Follow ChatGPT setup to connect a private tunnel on your Mac to your own account. First-time setup is currently an advanced installation.

  2. Enable Allow changes from remote connections in the extension settings and select Save if you want to manage tasks through the tunnel.

  3. Start a new conversation with the connection enabled and ask it to check the Things MCP connection. After setup, the background connection starts at login and does not need an open Terminal.

Other clients can use the standard local MCP transport. See other MCP clients. A model needs a client that supports tools; support for MCP alone does not guarantee compatibility with every host.

Related MCP server: Things MCP

What works

Workflow

What you can do

Find and review

Search tasks, projects, areas and tags; query built-in lists and date filters.

Plan your day

Create tasks, edit notes, schedule dates, set deadlines, complete and reopen tasks.

Organize your work

Manage projects, areas and tags; move projects with task counts and descendant summaries.

Checklists and templates

Create checklists and project templates, duplicate items, set reminders and Evening through Things URLs.

Clean up deliberately

Move items to recoverable Trash with separate permission; restore open tasks and projects.

Operation

Version 1.0.3

Search and read to-dos, projects, areas, and tags

Available

Create an Inbox to-do

Available

Edit a to-do's title and notes

Available

Set or clear a deadline

Available

Schedule a to-do on a calendar date

Available

Complete, cancel, or reopen a to-do

Available

Create and edit projects, areas, and tags

Available

Built-in list queries and project/area filters

Available

Moves between supported lists, projects, and areas

Available

Delete an individual task to Trash

Available with Trash permission

Create, replace, append or prepend checklist rows

Available through Things URLs

Create project templates with headings

Available through Things URLs

Move a task to an existing heading

Available through Things URLs

Duplicate a task or project

Available through Things URLs

Set Evening or a reminder time

Available through Things URLs

Restore open tasks and projects from Trash

Available

Delete projects, areas and tags

Available with container permission

Tag assignment, hierarchy and keyboard shortcuts

Available

Counts, selection, date filters and resumable searches

Available

Edit section headings inside a project

Not available

Create or change repeating schedules

Not available

Project moves return task counts and observed descendant changes in the same receipt. See project move results for the counts, changed-task details and read-back limits.

URL operations require one-time local setup for edits and duplication. Their receipts say “Sent to Things; result not verified” because Things does not expose complete read-back for those fields.

Native repeat-rule editing, full checklist/heading reads, arbitrary ordering and verified whole-library maintenance are unavailable. The capability reference explains field limits, search behavior, and unavailable features. Tools return their current implementation status through things_capabilities.

Try it in a conversation

Start with a connection check:

Use Things MCP to check the connection without reading or changing tasks.

Then try a read:

Show up to ten open Inbox tasks, without notes.

With Allow changes enabled:

Create one Inbox task called “Try Things MCP”, then read it back.

More everyday examples →

Requirements

  • A Mac with Things 3 installed and running before you launch your LLM client. Native checks used Things 3.23.3 and 3.23.4.

  • A client that supports the chosen connection. The packaged local route uses Claude Desktop; remote use depends on your ChatGPT account's available plugin and tunnel features.

  • macOS Automation permission to control Things when requested.

  • For remote access, the Mac must remain awake, online, and signed in.

Things and client subscriptions are separate products. This repository does not include Things, a subscription, or a vendor runtime license grant.

Your data and permissions

Task content requested in a conversation is shared with that client and its provider. The bridge does not collect Things Cloud credentials, write to the Things database, or provide a shell tool. No telemetry destination is bundled.

Writes require your local grant. Moving a task to Things’ recoverable Trash requires an additional permission so you can allow editing without allowing deletion. Every mutation checks permission and uses a durable request ID. Native task edits verify the exposed result in Things. URL tools report dispatch separately and do not claim a verified result. Edits also require the current item revision. Uncertain writes are never automatically repeated with a new request ID. These checks reduce duplicate and stale edits; Things automation is not transactional and cannot promise automatic rollback.

Local and remote connections share the same permission store, write lock, and request journal. See Security for the trust boundary and private vulnerability reporting.

Explore the project

Guide

What you will find

Installation

Step-by-step setup, permissions, updates and removal

Capabilities · Full scope

Available fields, read-back limits and unsupported operations

Privacy · Security

Data handling, trust boundaries and private vulnerability reporting

Verification · Changelog

Tested environments, remaining checks and release history

Contributing · Maintainer wiki

Development setup and architecture

Support and contribution

  • For a bug or feature request, open an issue with versions and a synthetic example. Keep task contents and credentials out of reports.

  • To contribute, follow Contributing. Developers can run the tests without Things, provider accounts, or personal configuration.

  • Financial support is optional and does not unlock features.

If Things MCP is useful to you, buy me a coffee.

Things MCP is an independent project. Product names identify compatibility; the project is not affiliated with or endorsed by the named vendors. Released under the MIT License. You may use, modify, and redistribute the code, including commercially, provided you retain its copyright and license notice. The software is provided without warranty. Third-party notices apply to their respective dependencies.

Available Tools

20 tools
things_apply_destructiveC
DestructiveIdempotent

Apply a previously reviewed scope using its current scope revision. Requires ordinary writes and the separate local owner grant for this action. Container deletion can cascade; empty Trash is permanent and global. Open-project, area and tag-hierarchy deletion are native verified. Global-command gates remain disabled pending their separate checks.

Inputs: action (required), requestId (required), expectedScopeRevision (required), target. Returns: result

things_capabilitiesA
Read-onlyIdempotent

Read the implementation and verification status of every operation family. Unavailable features cannot be invoked.

Inputs: no named parameters. Returns: result

things_count_itemsA
Read-onlyIdempotent

Count matches in a scan segment. Follow nextScanOffset and sum counts until scanComplete; concurrent Things edits can change totals. Uses the same filters as find. Offset must be zero.

Inputs: kind, list, text, limit, +13 more. Returns: result

things_create_from_templateA
Idempotent

Send one structured to-do or project to Things. Supports checklist rows and initial project headings. Requires writes. URL receipt confirms dispatch only: Things exposes no complete read-back or returned IDs here. Inspect Things; never retry with a new request ID.

Inputs: item (required), requestId (required). Returns: result

things_create_itemB
Idempotent

Create a to-do, project, area, or tag. Supply a unique UUID requestId. Creation of all four kinds is native verified. Local write permission is required and disabled by default.

Inputs: kind (required), title (required), requestId (required), notes, +13 more. Returns: result

things_duplicate_itemA
Idempotent

Ask Things to duplicate a to-do or project through its documented URL command. Requires writes, current revision and the local Keychain URL token. Repeating items cannot be duplicated. Receipt contains the source ID, not a new item ID, and does not confirm completion. Inspect Things before another request.

Inputs: target (required), requestId (required), expectedRevision (required), title. Returns: result

things_edit_extrasA
DestructiveIdempotent

Send checklist replacement/append/prepend, heading placement or scheduling including reminders/Evening/clearing to Things. Requires writes, current revision and the local Keychain URL token. Checklist replacement replaces every row. These fields cannot be read back; receipt is unverified dispatch. Repeat templates may reject these changes.

Inputs: target (required), changes (required), requestId (required), expectedRevision (required). Returns: result

things_existsA
Read-onlyIdempotent

Check whether an item exists by kind and ID. Automation errors are not reported as absence.

Inputs: id (required), kind (required). Returns: result

things_find_itemsA
Read-onlyIdempotent

Find items by type, text, status, tag ID, date range, selected items, list or parent. Optional sorting changes result order only. Follow nextScanOffset with offset zero to continue beyond 5000 objects. Results are not a snapshot. Fetch before editing.

Inputs: kind, list, text, limit, +13 more. Returns: result

things_get_itemA
Read-onlyIdempotent

Read one Things item by kind and stable ID, including its revision for safe editing.

Inputs: id (required), kind (required). Returns: result

things_healthA
Read-onlyIdempotent

Check the local Things connection, timezone, ordinary-write permission, and separate Trash permission.

Inputs: no named parameters. Returns: result

things_move_itemA
DestructiveIdempotent

Move a to-do to a project or area, a project to an area, detach a parent, or move a to-do to Inbox, Today, Anytime, or Someday. Projects support Today and Someday. Project Anytime and direct Logbook moves are unavailable. Project moves return descendantImpact with compared/changed task counts and up to 20 changed IDs with field names. Counts describe exposed fields, not every inherited effect. Requires the latest revision and write permission. Does not reorder items, address headings, or restore Trash.

Inputs: target (required), requestId (required), destination (required), expectedRevision (required). Returns: result

things_navigateA
Idempotent

Show an item or built-in list, open a task/project for editing, or show Quick Entry on this Mac. Requires write permission. Reports command acceptance, not task creation or visibility on another device.

Inputs: action (required), requestId (required), list, target. Returns: result

things_preview_destructiveA
Read-onlyIdempotent

Inspect the exposed scope of project/area/tag deletion, emptying Trash, or logging completed items. Returns a scope revision. Never grants permission. Checklist, heading and repeat-template content cannot be enumerated; Things does not provide atomic scope locking. Check health for native execution gates.

Inputs: action (required), target. Returns: result

things_request_statusA
Read-onlyIdempotent

Check the local receipt for a mutation request ID. Pending or unknown means inspect Things before any further write; do not create a new ID as an automatic retry.

Inputs: requestId (required). Returns: result

things_restore_itemA
Idempotent

Restore one open to-do to Inbox or one open project to Today from Trash. Requires normal writes, a current revision and a unique request ID. Closed items are not enabled. Restore a trashed project before addressing its children. Trashed project children cannot be enumerated before restoration; the receipt verifies exposed root fields and destination.

Inputs: target (required), requestId (required), expectedRevision (required). Returns: result

things_schedule_itemA
DestructiveIdempotent

Schedule a to-do or project on an explicit calendar date in the Mac timezone. Requires its current revision and a unique UUID requestId. Does not set reminders or repeating rules.

Inputs: date (required), target (required), requestId (required), expectedRevision (required). Returns: result

things_show_viewA
Idempotent

Open search or a built-in Things view, optionally filtering by tags. This changes the Mac's view only. Requires writes and a request ID; receipt confirms URL dispatch, not a visible result or returned task data.

Inputs: view (required), requestId (required), tags, query. Returns: result

things_trash_itemA
DestructiveIdempotent

Move one open to-do, including any checklist it contains, to Things Trash on the Mac. Read it and review the target first. Requires the latest revision, a unique request ID, ordinary write permission, and the separate local Trash grant. Does not permanently delete, empty Trash, or delete projects, areas or tags.

Inputs: target (required), requestId (required), expectedRevision (required). Returns: result

things_update_itemA
DestructiveIdempotent

Edit supported fields, or complete/cancel/reopen a to-do or project. Use the latest revision and a unique UUID requestId. Omitted fields stay unchanged; deadline null clears it. No deletion or arbitrary property editing.

Inputs: target (required), changes (required), requestId (required), expectedRevision (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 20 tools

    Disambiguation4/5

    Most tools map to a distinct resource and action, and the paired destructive preview/apply flow is clearly separated. Minor overlap exists between create_item and create_from_template, and between schedule_item and edit_extras, so an agent must read descriptions carefully to pick the right one.

    Naming Consistency4/5

    All tools share the things_ prefix and use snake_case, with mostly verb_noun names like get_item, create_item, and restore_item. A few names are noun-only or less conventional (things_capabilities, things_health, things_exists, things_request_status), making the pattern slightly inconsistent.

    Tool Count3/5

    20 tools falls into the 16-25 range that feels heavy for a server. That said, each tool addresses a distinct operation or safety gate, so the count is still defensible for a full Things integration.

    Completeness4/5

    The surface covers create, read, update, move, schedule, duplicate, trash/restore, and reviewed destructive actions, which is strong lifecycle coverage for the domain. Minor gaps remain, such as no direct read-back for template-created items, no project-to-Logbook move, and disabled global destructive gates.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers