SupaThings

npm version License Node

SupaThings MCP is a Things 3 MCP server for macOS.

It was built to solve a practical gap: AI agents can write to Things via things:///, but they cannot reliably understand your real project structure from URL commands alone.

SupaThings combines SQLite-based reads with official URL-scheme writes, so agents can both understand and act safely.

Table of Contents

• Quick Start
• What This MCP Server Does (and Why It Exists)
• Current Scope (v0.4.0)
• How It Works
• Things-Native Philosophy
• Recommended Workflows
• Available Tools
• Token and Context Efficiency
• Requirements
• Build and Smoke Tests
• Packaging and Release
• Project Structure
• Attribution
• Support
• License

Quick Start

1) Run with npx (no install)

npx -y supathings-mcp

2) Global install from npm

npm install -g supathings-mcp

Alias also available:

things-mcp

3) Build from source

npm install
npm run build
node dist/index.js

4) MCP config example

{
  "mcpServers": {
    "supathings": {
      "command": "npx",
      "args": ["-y", "supathings-mcp"]
    }
  }
}

5) Configure MCP in your client (copy/paste)

Codex:

codex mcp add supathings -- npx -y supathings-mcp

Claude Code:

claude mcp add --transport stdio supathings -- npx -y supathings-mcp

Gemini CLI:

gemini mcp add -s user supathings npx -y supathings-mcp

What This MCP Server Does (and Why It Exists)

MCP servers expose tools over a standard protocol so AI clients can call them programmatically.

In Things, there are two realities:

• The things:/// URL scheme is excellent for creating/updating/navigating items.
• URL commands alone do not expose full structural context (project hierarchy, headings, checklist relationships, planning summaries).

SupaThings was built to bridge that split.

Technical approach:

• Read path: query local Things SQLite data for structure and context.
• Write path: execute official things:/// URL actions for safe interoperability.
• Planning path: add semantic tools for heading inference, validation, project summaries, and task placement.

Why this is useful in practice:

• Better decisions: agents can place tasks under the right heading.
• Lower token usage: compact structural answers instead of large raw dumps.
• Safer automation: writes stay on official Things-supported surfaces.
• More predictable workflows: clear split between data understanding and data mutation.

Current Scope (v0.4.0)

Current release: 0.4.0

Shipped scope today:

• Tool surface: 37 MCP tools
• Read model: local Things SQLite database (areas, projects, headings, todos, tags, checklist items)
• Write model: official things:/// URL scheme
• Semantic layer: heading inference, heading validation, project structure summaries, task placement suggestions
• Optional AppleScript actions: runtime-gated

Current boundaries:

• macOS + local Things installation required
• recurring template rows are intentionally excluded from read queries
• headings are easiest to guarantee at project creation time
• adding missing headings to existing projects remains constrained by Things capabilities

How It Works

Three-layer model:

• SQLite layer for rich reads of local Things data
• things:/// layer for writes, updates, moves, and navigation
• AppleScript layer for optional lightweight app actions (show-quick-entry, log-completed, empty-trash)

This split is deliberate: read from local truth, write through supported Things APIs.

Things-Native Philosophy

SupaThings is opinionated here: Things should be treated like Things.

Headings are modeled as semantic groupings (categories, work blocks, deliverables), not as a Jira-style workflow board by default.

That changes:

• how headings are inferred
• how project summaries are generated
• how task placement is suggested

Recommended Workflows

New project with headings

Use when the project does not exist yet:

1. suggest-headings
2. create-project-with-headings
3. optionally verify with get-projects or get-project-structure

Existing project missing headings

Use when the project already exists but needs structure:

1. get-headings or suggest-headings
2. create missing headings manually in Things
3. validate-headings
4. create or move tasks into those headings

Why: creating headings is most reliable during brand-new project creation.

Existing project with structure already in place

1. get-project-structure
2. summarize-project
3. suggest-task-placement
4. create or move tasks into the chosen headings

Available Tools

Current exposed tools: 37

Category	Tools
Read and inspection	app-status, version, get-areas, get-tags, get-projects, get-headings, get-project-structure, get-todos, get-inbox, get-today, get-upcoming, get-anytime, get-someday, get-logbook, get-trash, get-tagged-items, get-recent, search-todos, search-items, search-advanced
Semantic planning	suggest-headings, validate-headings, suggest-task-placement, summarize-project
Write and navigation	add-todo, add-project, create-project-with-headings, update, update-project, update-todo, show, show-item, search, json
Optional AppleScript	show-quick-entry, log-completed, empty-trash

If Apple Events are unavailable, these fail gracefully.

Token and Context Efficiency

SupaThings is designed to reduce context burn in AI workflows.

Current efficiency features:

• concise text responses
• structured payloads without duplicating full JSON in text output
• detail: "compact" | "full" on major read/search tools
• limit on major list/search tools
• get-project-structure for lightweight structural inspection
• summarize-project for planning-focused summaries
• suggest-task-placement for semantic placement suggestions

Requirements

• macOS
• Things 3 installed locally
• Node.js 22+
• npm 10+
• Apple Events permission only if you want optional AppleScript actions

Build and Smoke Tests

npm run build
npm run smoke
npm run smoke:mcp

Smoke coverage includes:

• server startup over stdio
• tool listing
• Things app availability
• SQLite access
• project and heading inspection
• semantic tools (suggest-headings, get-project-structure, suggest-task-placement, summarize-project)

Packaging and Release

Create local tarball

npm pack

Full release guide

See:

• docs/PUBLISHING_GUIDE.md

Quick release summary:

1. Validate build and smoke tests.
2. Commit and push to your GitHub repo.
3. Create and push an annotated tag (for example v0.4.0).
4. Create a GitHub release from that tag.
5. Publish to npm (npm publish --access public).
6. Verify npx -y supathings-mcp and client setup commands.

Project Structure

• src/index.ts: MCP server entrypoint
• src/views.ts: compact/full serializers
• src/headings.ts: heading semantics and inference
• src/project-structure.ts: project structural analysis
• src/task-placement.ts: heading placement suggestions
• src/project-summary.ts: planning-oriented summaries
• scripts/smoke-test.mjs: structural environment smoke test
• scripts/mcp-smoke.mjs: MCP protocol smoke test
• scripts/install-clients.sh: multi-client MCP installer
• scripts/uninstall-clients.sh: multi-client MCP uninstall helper
• docs/PUBLISHING_GUIDE.md: GitHub + npm publication guide

Attribution

This project builds on prior work and ideas from:

• jimfilippou/things-mcp
• hald/things-mcp
• thingsapi/things.py

Licensing and attribution details are included in LICENSE and NOTICE.

Support

• 🐛 Bug Reports: Open an issue on GitHub (Issues)
• 💡 Feature Requests: Open an issue with enhancement label (New issue)
• 📚 Documentation: Check the Things URL scheme docs (Things URL Scheme)
• 💬 Questions: Open a discussion on GitHub (Discussions)

License

Apache-2.0. See LICENSE and NOTICE.