# 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.

```sh
codex plugin marketplace add alfonsopuicercus/things-mcp --ref v0.1.1
codex plugin add things-mcp-alfonso@alfonso-things-local
```

Reload 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](https://github.com/alfonsopuicercus/things-mcp/releases/tag/v0.1.1) · [Report a problem](https://github.com/alfonsopuicercus/things-mcp/issues)

## 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.

1. Download the archive, its `.sig` and `.sha256` files from the [release page](https://github.com/alfonsopuicercus/things-mcp/releases/tag/v0.1.1). Obtain the public key and standalone verifier independently from the trusted [original repository](https://github.com/alfonsopuicercus/things-mcp), not from an unverified archive.
2. Original public-key fingerprint (SHA-256 of SPKI DER): `7bd05f2ebd1f17f452c36e8aa6cc057ae77bd1f6d2b608c012db874d8e9fd23a`. The key is in `signing/release-public.pem`; the standalone verifier is `scripts/verify-release.mjs`. A key bundled with an archive is not independently trusted just because it verifies its own signature.
3. 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.
4. Register with Codex: `codex mcp add things-alfonso -- node /absolute/path/to/ThingsMCP/dist/server.mjs`.
5. 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 |
| --- | --- |
| `things_health` | App/server identity, availability and mode |
| `things_list_items` | Paged task/project/area summaries; title search and container filters |
| `things_get_task` | Task details and modification timestamp |
| `things_create_task` | One new task; Inbox or a project/area |
| `things_update_task` | Title, notes, deadline and existing tags; read back changed fields |
| `things_move_task` | Move to a supported list, project, or area |
| `things_schedule_task` | Set the start date using the Mac's calendar timezone |
| `things_complete_task` | 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](https://github.com/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](PRIVACY.md) and [AUTHOR.md](AUTHOR.md).

License: [MIT](LICENSE), 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](https://culturedcode.com/things/support/articles/4562654/), [OpenAI plugin packaging](https://developers.openai.com/plugins/build/plugins), [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), [npm provenance](https://docs.npmjs.com/generating-provenance-statements/).