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.

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 navig

... View full README on GitHub