Integrates with the Things 3 personal task manager on macOS, allowing AI agents to read project structures via SQLite, create items using the official URL scheme, and manage tasks, headings, and areas.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SupaThings MCP Summarize my 'Home Renovation' project and suggest some headings"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: Things MCP
npx -y supathings-mcpnpm install -g supathings-mcpAlias also available:
things-mcpnpm install
npm run build
node dist/index.js{
"mcpServers": {
"supathings": {
"command": "npx",
"args": ["-y", "supathings-mcp"]
}
}
}Codex:
codex mcp add supathings -- npx -y supathings-mcpClaude Code:
claude mcp add --transport stdio supathings -- npx -y supathings-mcpGemini CLI:
gemini mcp add -s user supathings npx -y supathings-mcpMCP 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 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
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.
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
Use when the project does not exist yet:
suggest-headings
create-project-with-headings
optionally verify with get-projects or get-project-structure
Use when the project already exists but needs structure:
get-headings or suggest-headings
create missing headings manually in Things
validate-headings
create or move tasks into those headings
Why: creating headings is most reliable during brand-new project creation.
get-project-structure
summarize-project
suggest-task-placement
create or move tasks into the chosen headings
Current exposed tools: 37
Category | Tools |
Read and inspection |
|
Semantic planning |
|
Write and navigation |
|
Optional AppleScript |
|
If Apple Events are unavailable, these fail gracefully.
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
macOS
Things 3 installed locally
Node.js 22+
npm 10+
Apple Events permission only if you want optional AppleScript actions
npm run build
npm run smoke
npm run smoke:mcpSmoke 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)
npm packSee:
docs/PUBLISHING_GUIDE.md
Quick release summary:
Validate build and smoke tests.
Commit and push to your GitHub repo.
Create and push an annotated tag (for example v0.4.0).
Create a GitHub release from that tag.
Publish to npm (npm publish --access public).
Verify npx -y supathings-mcp and client setup commands.
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
This project builds on prior work and ideas from:
Licensing and attribution details are included in LICENSE and NOTICE.
🐛 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)
Inputs: title (required), notes, when, deadline, +9 more.
Inputs: title, titles, notes, when, +14 more.
Inputs: no named parameters.
Inputs: title (required), goal, work_type, methodology, +10 more.
Inputs: no named parameters.
Inputs: detail, limit.
Inputs: include_items.
Inputs: project_uuid, include_items, detail, limit.
Inputs: detail, limit.
Inputs: period, limit, detail.
Inputs: include_items, status, area, query, +2 more.
Inputs: project_uuid (required).
Inputs: period (required), detail, limit.
Inputs: detail, limit.
Inputs: tag (required), detail, limit.
Inputs: include_items.
Inputs: detail, limit.
Inputs: project_uuid, include_items, list, area, +4 more.
Inputs: detail, limit.
Inputs: detail, limit.
Inputs: data (required), auth-token, reveal.
Inputs: ids (required).
Inputs: query.
Inputs: status, start_date, deadline, tag, +5 more.
Inputs: query (required), detail, limit.
Inputs: query (required), detail, limit.
Inputs: id, query, filter.
Inputs: id (required), query, filter_tags.
Inputs: withAutofill.
Inputs: project_uuid, project_title, goal, work_type, +1 more.
Inputs: project_uuid (required), task_titles (required).
Inputs: project_uuid (required).
Inputs: id (required), auth-token, title, notes, +19 more.
Inputs: id (required), auth-token, title, notes, +14 more.
Inputs: id (required), auth-token, title, notes, +10 more.
Inputs: project_uuid (required), expected_headings (required).
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 37 tools
Multiple tools have unclear boundaries and overlapping purposes, such as search/search-advanced/search-items/search-todos and show/show-item, which could cause confusion and misselection. While some tools like get-inbox and get-today have distinct purposes, the significant overlap in search and display functions creates ambiguity.
The naming follows a mostly consistent verb-noun pattern with hyphens (e.g., get-projects, update-todo), but there are deviations like json, version, and show without clear nouns, and inconsistencies such as add-project vs create-project-with-headings. The pattern is readable but mixed in style.
With 37 tools, the count is too high for the apparent task management domain, suggesting bloat and potential redundancy, as seen with multiple search and get variants. This many tools can overwhelm agents and indicate poor scoping, though it's not extreme like 50+.
Inferred as a task/project management system, the tool set covers core CRUD operations (add, get, update, delete via trash), lifecycle aspects (log-completed, summarize-project), and advanced features like search and suggestions, with only minor gaps such as potential missing bulk operations or detailed configuration tools.
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
