Things MCP

Things MCP connects an OAuth-capable MCP client to your Things 3 tasks on a Mac. It supports reading tasks, listing the Inbox, creating tasks, editing titles and notes, and completing or reopening tasks. You host a Cloudflare gateway and a local macOS service; each deployment serves one Things owner.

Installation

You need a Mac running Things 3 in your logged-in account, Node 26.13.0, Apple command-line developer tools, and a Cloudflare account with a domain, Workers, KV, Access, and Tunnel. The Mac must remain available for task access.

Clone a release, then install and build on the Mac that will run the service:

git clone https://github.com/lexijamesesq/things-mcp.git
cd things-mcp
git checkout things-mcp--v0.1.0
npm ci
npm run build:native

Follow the installation guide to configure the gateway, create the local journal and LaunchAgent, and authorize Automation once. Releases ship source; the native helper and SQLite dependency are built for your Mac. There is no hosted service or prebuilt, notarized application to download.

Required configuration

The configuration tables and setup commands describe every required value. Keep credentials and installation files outside this repository.

Related MCP server: Things Cloud MCP

What's Included

Usage

Connect an MCP client

Add https://YOUR_HOST/mcp as a remote Streamable HTTP MCP endpoint in a client that supports OAuth. Sign in as the configured owner and approve the requested scopes. The default grant is things.read; write tools require explicit additional scopes. Client configuration and consent are your choice and are not installed by the server.

Read and change tasks

For example, read a task with things_get, then pass its returned revision to an update. Generate one UUID per intended mutation and retain it for recovery:

{
  "operationId": "019a7234-4580-7000-8000-000000000001",
  "id": "NATIVE_TASK_ID",
  "expectedRevision": "REVISION_FROM_THINGS_GET",
  "notes": null
}

This things_update call clears notes. Omitted fields stay unchanged. Do not reuse the example UUID for separate operations. See the tool contract for arguments, pagination, conflicts, and uncertain outcomes.

Dates, tags, moves, projects, areas, checklists, reminders, recurrence rules, and lists other than Inbox are unsupported. Read-by-ID can reach tasks outside Inbox. The service cannot identify a repeating template's relationship to its instances. See compatibility and evidence limits.

Operate the service

"$HOME/Library/Application Support/ThingsMCP/things" status
"$HOME/Library/Application Support/ThingsMCP/things" doctor
"$HOME/Library/Application Support/ThingsMCP/things" logs

The operations guide covers backups, upgrades, rollback, permission failures, and recovery after an interrupted write.

How It Works

The client authenticates to the Worker using OAuth with PKCE. Cloudflare Access protects the owner sign-in route. The Worker forwards each authorized request through Tunnel with a short-lived signature bound to its method, path, content type, body, owner, client, and scopes. The origin also requires a service Access credential. One hostname carries both the public endpoints and protected origin.

The local service listens only on loopback. A SQLite journal records mutation IDs and outcomes before dispatch. Writes are serialized and compare a fresh task revision with the client's revision. Results expire after seven days; deduplication records remain so an old request cannot silently become a new write.

Task operations do not open windows or request permission. If Things is closed, the service attempts background startup; macOS may display a window during that startup. The owner must be logged in with an unlocked console session. Health checks do not launch Things. Automation permission is granted explicitly during installation.

Security

Deploy for one owner. The journal can contain task content and needs the same protection as your Things data. Cloudflare handles OAuth state and request traffic; review that trust boundary before deployment. Keep private signing keys, service tokens, Tunnel credentials, and backups outside Git with owner-only permissions.

A revision check is not an atomic transaction with Things: an external edit can race a write. An ambiguous native result is recorded as uncertain and is never automatically retried. Request signing and the service credential are both required even when a caller can reach the origin.

Development

npm run typecheck
npm test
THINGS_SIGNING_KID=local-check npm run build:worker

The local-check key ID is for build verification only; deployment must use the key ID trusted by the installed service.

Tests use Vitest and isolated fixtures; manual live acceptance scripts are excluded from the default suite. See release maintenance for versioning, reviewed source tags, and the distinction between publishing and deployment.

License

MIT. See LICENSE.