Things MCP
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., "@Things MCP Show me what's on my Today list in Things."
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.
Things by Alfonso
A local Things 3 MCP integration by Alfonso Puicercus Gomez. Version 0.1.1 is an early MIT-licensed release for macOS.
The MCP server runs on your Mac and talks to Things through its supported scripting interface. It does not need an OpenAI API key, a Things Cloud login, or a hosted service. Your MCP client applies its own permissions and sends tool results to its model according to that client's settings.
Install as a Codex plugin
Requires macOS, Things 3, Node.js 22 or later, and Codex with local plugin support.
codex plugin marketplace add alfonsopuicercus/things-mcp --ref v0.1.1
codex plugin add things-mcp-alfonso@alfonso-things-localReload Codex, then ask “Use Things by Alfonso to read my Today list.” The repository includes a prebuilt server; end users do not need to install npm dependencies. macOS may ask for permission to control Things. If your client cannot find Node, use its absolute executable path or the direct MCP setup below. This release was tested on the author's Mac; another Mac has not yet been independently tested.
Download v0.1.1 · Report a problem
Related MCP server: Things MCP
Use the bundled release
Requirements: macOS, Things 3, Node.js 22 or later, and an MCP client with local stdio support. Node must be available on the client's PATH; an absolute Node path can be used instead.
Download the archive, its
.sigand.sha256files from the release page. Obtain the public key and standalone verifier independently from the trusted original repository, not from an unverified archive.Original public-key fingerprint (SHA-256 of SPKI DER):
7bd05f2ebd1f17f452c36e8aa6cc057ae77bd1f6d2b608c012db874d8e9fd23a. The key is insigning/release-public.pem; the standalone verifier isscripts/verify-release.mjs. A key bundled with an archive is not independently trusted just because it verifies its own signature.Before extracting or executing archive contents, verify using an independently trusted copy of the standalone verifier:
node /trusted/path/verify-release.mjs /absolute/path/to/things-mcp-alfonso-0.1.1.tar.gz /absolute/path/to/trusted-public-key.pem EXPECTED_FINGERPRINT. Obtain that verifier through a trusted author-controlled channel. The copy inside an unverified archive cannot establish trust in itself. Then extract into a permanent folder.Register with Codex:
codex mcp add things-alfonso -- node /absolute/path/to/ThingsMCP/dist/server.mjs.Start a new chat or reload MCP connections. If macOS prompts for Automation access, allow your MCP client to control Things.
The release contains a bundled server, so using it does not require npm install. The author signature is an Ed25519 detached archive signature, not Apple Developer ID code signing or notarization.
Try: “Read my Things Today list”, “Find tasks about TestBeam”, or “Create a task in my Inbox”. IDs, not titles, select tasks for writes. Start dates and deadlines are separate.
Tools
Tool | Behavior |
| App/server identity, availability and mode |
| Paged task/project/area summaries; title search and container filters |
| Task details and modification timestamp |
| One new task; Inbox or a project/area |
| Title, notes, deadline and existing tags; read back changed fields |
| Move to a supported list, project, or area |
| Set the start date using the Mac's calendar timezone |
| Complete an exact task ID and verify status |
Read pages default to 20 items and are capped at 100. Summaries omit notes; task details cap notes at 10,000 characters. status defaults to open; use status: "any" when checking Logbook or completed projects. Tasks exclude project objects. expected_modified_at is an optional guard against stale edits, not a transactional lock against external changes during the operation. A write is reported successful only after read-back verification. Task contents are untrusted data, not instructions.
No task deletion, recurrence editing, checklist/heading editing, deadline clearing, bulk mutations, or automatic Obsidian sync. Tags must already exist; failed verification may mean a partial edit occurred. Never automatically retry an ambiguous create or edit: read the task or search for its title first.
Read-only mode
Register with codex mcp add things-alfonso --env THINGS_MCP_READ_ONLY=1 -- node /absolute/path/to/ThingsMCP/dist/server.mjs to block all writes. Remove the setting when you choose to enable editing. MCP tool annotations are hints; the server's read-only flag is enforced before automation begins.
Local plugin packaging
plugin.json and mcp.json use the Agent Plugins portable layout. A compatibility .codex-plugin/plugin.json and .mcp.json are included. The local marketplace is .agents/plugins/marketplace.json.
To register that local marketplace: codex plugin marketplace add /absolute/path/to/ThingsMCP. Install the plugin from that local source in a compatible desktop client, then reload the app. Portable plugin and marketplace support varies by client; direct stdio registration above is the tested fallback. Enable either the plugin or direct MCP connection, not both, to avoid duplicate tools.
This is a Mac-local integration, not a universal cloud connector. The current OpenAI public MCP submission route expects a remote HTTPS endpoint. Do not expose this stdio server or the Things database over an unauthenticated network endpoint just to meet that requirement.
Development
Run npm ci --ignore-scripts, npm test, npm run build, and npm run smoke. npm run doctor checks direct Things access.
npm run smoke:write explicitly creates a uniquely labeled disposable test task, edits/schedules/moves/completes it, then moves only that task to Trash. It does not empty Trash or alter other tasks. Live smoke tests require macOS and Automation access; unit tests can run elsewhere. Creating a task is not automatically retried on failure.
npm run release reruns source tests, rebuilds the executable, checks bundled MCP reads, then signs a versioned archive. The signing key is created at ~/Library/Application Support/ThingsMCP/signing/release-private.pem (mode 0600), outside the source tree and release archive. Back it up securely; losing it breaks signing-key continuity. Increment the version before making another archive. Nothing in the release script publishes to a registry or creates a public repository.
Attribution and measurement
Author metadata, copyright notice, public release key and release checksums identify the project and support release verification. The original source is published under alfonsopuicercus/things-mcp; npm provenance can tie a published package to its source/build workflow.
There is no network telemetry. Optional local aggregate counters are enabled only by setting THINGS_MCP_METRICS_DIR to a private data directory. They store tool names and success/failure counts, not task content or identifiers. They remain on the user's Mac and do not give the author usage statistics.
Run npm run stats from a source checkout (or node scripts/stats.mjs from the release) to see public GitHub release archive download counts. This explicit command queries GitHub; the MCP server never runs it. Downloads indicate adoption, but are not unique users or active usage. Active usage measurement requires an explicitly disclosed opt-in telemetry service, separately designed and deployed. That service is outside version 0.1.1. See PRIVACY.md and AUTHOR.md.
License: MIT, copyright 2026 Alfonso Puicercus Gomez. Copies must retain the copyright and license notice. Independent project; not affiliated with Cultured Code or OpenAI.
Sources: Things scripting commands, OpenAI plugin packaging, Codex MCP, npm provenance.
Available Tools
8 toolsthings_complete_taskADestructiveIdempotent
Mark one exact task ID complete and read back its completed status. Already completed tasks are left as-is.
Inputs: id (required), expected_modified_at.
things_create_taskADestructive
Create one task in Inbox, or a specified project/area, and read it back. Do not retry an ambiguous failure without searching for the created task.
Inputs: title (required), tags, notes, area_id, +2 more.
things_get_taskARead-onlyIdempotent
Read one task by exact ID, including notes (capped at 10,000 characters) and modification timestamp.
Inputs: id (required).
things_healthARead-onlyIdempotent
Check local Things availability, server identity, read-only mode, and tracking policy.
Inputs: no named parameters.
things_list_itemsARead-onlyIdempotent
Read a bounded page of task summaries, projects, or areas. Notes are omitted. Filter tasks by list, project_id, area_id or title query. Use returned IDs for edits.
Inputs: kind, list, limit, query, +4 more.
things_move_taskADestructive
Move a task to a project/area by ID or Inbox/Today/Anytime/Someday. Verify destination membership. Scheduling is separate.
Inputs: id (required), kind (required), target (required), expected_modified_at.
things_schedule_taskBDestructive
Set a task start date, separately from its deadline, in local macOS calendar time (YYYY-MM-DD). Verify it through the activation date or Today membership.
Inputs: id (required), date (required), expected_modified_at.
things_update_taskADestructive
Update specified title/notes/deadline/tags of an exact task ID and verify each field. Notes and tags replace existing values. expected_modified_at guards against stale edits. Deadlines use YYYY-MM-DD; clearing deadlines is outside v0.1.
Inputs: id (required), tags, notes, title, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct operation: create, list, get, update, move, schedule, complete, and health. The boundaries between update (fields), move (container), and schedule (start date) are explicitly clarified in the descriptions, leaving no meaningful overlap.
All tools use the consistent 'things_' prefix and a verb_noun pattern (create_task, list_items, get_task, etc.). The only deviation is 'things_health', which lacks a verb, but it is still clearly readable and predictable.
Eight tools is well-scoped for a task management server, covering the essential lifecycle operations without bloat. Each tool earns its place and the set feels complete for typical task workflows.
The surface covers create, read, update, move, schedule, complete, and health, which handles most task operations. However, there is no delete or reopen/uncomplete tool, and project/area creation is absent, which are minor but notable gaps in the lifecycle.
Maintenance
Related MCP Connectors
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Read and write Mission Control state via MCP — projects, tasks, subtasks, templates, status updates.
Issues, projects, cycles, and roadmaps via the official Linear hosted MCP server.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server that gives AI agents read/write access to your Things3 tasks via the Things API.321Apache 2.0
- AlicenseNot gradedqualityDmaintenanceRead-only MCP server for Things 3 to retrieve completed tasks by date, weekly summaries, and project reports for analysis and reflection.12 npmISC
- AlicenseAqualityDmaintenanceComposite MCP server for Things 3 on macOS that bundles multiple read calls into single requests, enables batch writes, and provides a self-healing read path to handle TCC protection issues.8MIT
- 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