Skip to main content
Glama

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

  1. Download the archive, its .sig and .sha256 files from the release page. Obtain the public key and standalone verifier independently from the trusted original repository, 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; 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 tools
things_complete_taskA
DestructiveIdempotent

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_taskA
Destructive

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_taskA
Read-onlyIdempotent

Read one task by exact ID, including notes (capped at 10,000 characters) and modification timestamp.

Inputs: id (required).

things_healthA
Read-onlyIdempotent

Check local Things availability, server identity, read-only mode, and tracking policy.

Inputs: no named parameters.

things_list_itemsA
Read-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_taskA
Destructive

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_taskB
Destructive

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_taskA
Destructive

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

    A3.9/5.0

    Scored across 8 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers