Skillget

SupaThings-MCP

mcp
SUMMARY

Things 3 MCP server for macOS with SQLite reads, official things:/// URL writes, and semantic planning tools for AI agents.

README.md

SupaThings MCP

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

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

Attribution

This project builds on prior work and ideas from:

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.

Reviews (0)

No results found