SupaThings MCP Server

SupaThings MCP

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.

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