suur-things-mcp 0.8.5

A safe, fast MCP server for the Things 3 task manager (Cultured Code) on macOS — reads from the local SQLite database, writes only through the official Things URL Scheme.

SUUR Things MCP

Give any AI agent safe, structured access to your Things 3 tasks — plus a local, Things-faithful web dashboard with Kanban boards, an Eisenhower matrix, repo-linking, and a YouTube-thumbnail card view.

An MCP server for Things 3 (Cultured Code) on macOS. Let Claude Code, Claude Desktop, Codex, or any MCP-capable agent read and manage your tasks, projects, and areas — and get a local dashboard that looks like Things but adds the views Things doesn't have.

Install → connect your agent → ask "what should I work on?"

# Connect it to Claude Code (Codex / Desktop below). uvx installs on first run.
claude mcp add suurthings -- uvx suur-things-mcp

Now ask your agent "What should I work on today?" — it reads your real Things lists and answers. Reads work immediately, no token. (Optional: uvx suur-things-mcp dashboard opens a local board at http://127.0.0.1:8765.) Add a token — see below — only when you want the agent to modify existing tasks.

---

What it is (and the one design decision that matters)

Two data paths, deliberately split:

• Reads come straight from the local Things SQLite database — instant and complete: Today, Upcoming, Inbox, Anytime, Someday, Logbook, Trash, full-text search, projects, areas, tags, and full item detail.
• Writes go only through the official Things URL Scheme — add to-dos/projects, update, complete, cancel, reschedule, move between projects, append checklist items.

Why this matters: Cultured Code's own AI-integration guidance is blunt — writing directly to the Things database is unsafe and can corrupt it. They endorse the URL Scheme as the safe automation path. This server follows that exactly: it reads the DB read-only and never writes to it. Every mutation is a things:/// URL, the same mechanism Things documents for Shortcuts and AppleScript.

So an agent can't corrupt your database through this server even if it tries. The worst a write can do is what the URL Scheme itself allows.

Privacy: an agent connected to this server can read your to-do and note content, which is then sent to whatever model you're using. Review your agent's privacy policy. Nothing here phones home; there's no telemetry and no bundled LLM.

Why not direct DB writes?

Because Cultured Code says not to. Their AI-integration guidance states plainly that writing to the Things SQLite database directly is unsafe and can corrupt it, and they point automation at the URL Scheme instead. So this server reads the database read-only and routes every change through things:/// URLs — the same path Things documents for Shortcuts and AppleScript. The upside for you: an agent connected here physically cannot corrupt your Things data, no matter what it does.

---

✨ Beyond Things — what the dashboard adds

uvx suur-things-mcp dashboard runs a local board (127.0.0.1:8765) that looks like Things but adds the views and superpowers it doesn't have. Everything here is layered on top — your Things data stays untouched (boards, priorities, time-blocks, and repo links live in a local overlay, never written to Things).

Plan & focus

• 🟦 Priority Matrix — an Eisenhower matrix (Do First / Schedule / Delegate / Don't Do) as a one-click view on any list, project, or area. Drag tasks (and an area's projects) into quadrants.
• 🏷️ Priority Levels — a 2×2 grid (P1–P4) over Today or any list/area/project, ranked from your existing Things tags. Map a tag to each level (e.g. 🔴 → P1); drag a task between levels and the tag is rewritten in Things. Unlike the Matrix, the source of truth is your real tags — read-only without a token, otherwise fully bidirectional.
• 🗂️ Area roll-up — open an area and see the tasks inside its projects, grouped by project, not just the area's loose to-dos. A true overview of everything under the area.
• 📅 Daily planning / time-blocking — a day Timeline view: drag today's tasks onto a 6am–11pm grid in 15/30/60-min blocks to plan the day. (Times are a private dashboard overlay.)
• 🧘 Calm Today — one keystroke turns an overloaded Today into a single next action plus a short list and defers the rest. AI that subtracts noise instead of piling on features.
• 🎯 Calm by design — faithful Things look, light/dark, focus-friendly; completed tasks linger checked-off until they log, like the app.

Build & ship (for devs)

• 🔗 Git repo links on projects — connect a Things project/area to one or more local repos. Cards and the project/area page get one-click Open in editor (⌨) / terminal (❯) / GitHub (↗), plus the git/GitHub pulse — even when the project isn't on a board.
• 📊 Repo pulse — board cards show recent commits + open-PR count for linked repos (via git + gh).
• 🧭 Project boards — saved portfolio Kanbans where each card is a whole project/area (progress ring + open count), dragged across your own stage columns.

Capture, find & tidy

• ⌘ Command palette (⌘K) — jump to any list/project/board, search tasks, create, switch view, and act on a task (complete / reschedule / move) — all keyboard-only.
• ➕ Natural-language quick-add — type buy milk tomorrow #errand and it's parsed into a real to-do.
• 🧹 Agent triage — Triage Inbox (propose a home + tags + date per item) and Organize (tidy titles/notes/tags). Your agent proposes; you review every change before anything is written.
• 🎬 Cards view — a project full of links becomes a wall of YouTube thumbnails (a perfect "watch later").
• 🏷 Tag filter chips + full-text search across everything; inline rename, column reorder, board-card progress rings.

All of it free, local, open source — built on the safe read-SQLite / write-URL-Scheme split. No cloud, no account, no telemetry.

---

Cool use cases — your agent + Things

These are the workflows this unlocks once an agent can see and shape your task system:

• Plan → project, instantly. Hand Claude an implementation plan and the plan_to_project prompt; it materializes a real Things project — a to-do per step with sub-tasks as checklist items — in one batch call. (Things' URL Scheme can't create headings, so phases get folded into titles/notes rather than faked.)
• "What should I work on in this repo?" Link a Things project to a local git repo. From inside that repo, the work_on_repo prompt resolves which project you're in (via CLAUDE_PROJECT_DIR / cwd), pulls its open to-dos, and works the next one.
• Sweep code TODOs into Things. Point your agent at the codebase: it greps TODO/FIXME, and batch-creates to-dos with file:line references — no new tool needed, the agent already has Grep + this server.
• Auto-organize a messy Inbox. Hit the ✨ button on any folder (or use the organize_folder prompt). It spawns your agent headlessly with zero tools and zero MCP, so it can only propose cleaner titles/notes/tags — never write or be prompt-injected. You review every change before it's applied. (And yes, an agent can re-file Inbox items into the right projects — update supports moving via list-id.)
• Natural-language capture, for free. Things has no NLP input — and you don't need it: tell your agent "add buy milk tomorrow 9am #errand" and it parses and creates it. The dashboard's ＋ also takes light shorthand (buy milk tomorrow #errand). Your agent is the natural-language (and recurring) layer Things lacks.
• AI that subtracts noise. Most todo apps win by adding features; this one makes a calm app smarter, not busier. calm_today turns an overloaded Today into one next action plus a short list; triage files your Inbox. The intelligence is for removing work from your face, not piling it on.
• One-call situational awareness. overview returns a whole-system digest (counts, today, overdue, projects with no next action, recent completions) in a single call instead of ten.

(The dashboard's visual features — Matrix, Timeline, Cards, boards, repo links — are in ✨ Beyond Things above.)

---

Requirements

• macOS with Things 3 installed
• uv (recommended) — or any Python ≥ 3.10

Install

uvx runs it with no manual install or virtualenv:

uvx suur-things-mcp            # run the MCP server over stdio
uvx suur-things-mcp dashboard  # run the dashboard instead

Claude Code

# read-only (no token)
claude mcp add suurthings -- uvx suur-things-mcp

# read + write (modify existing items) — pass your token
claude mcp add suurthings --env THINGS_AUTH_TOKEN=your-token-here -- uvx suur-things-mcp

Claude Desktop / Codex / other MCP clients

Add to your client's MCP config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "suurthings": {
      "command": "uvx",
      "args": ["suur-things-mcp"],
      "env": { "THINGS_AUTH_TOKEN": "your-token-here" }
    }
  }
}

THINGS_AUTH_TOKEN is optional. Without it you can read everything and create new to-dos/projects. It's only needed to modify existing items.

Bleeding edge (straight from main, before a release lands on PyPI)

uvx --from git+https://github.com/artyomsklyarov/suur-things-mcp suur-things-mcp

Getting your Things auth token

1. Things → Settings → General
2. Enable "Enable Things URLs"
3. Click Manage and copy the token

Keep it secret — it grants write access via the URL Scheme. It's stored locally (see below), never in this repo.

Updating

There's no custom "update" command — updates ride on whatever fetched the package. uvx caches, so:

uvx --refresh suur-things-mcp        # re-fetch the latest release, then restart your MCP client

If you installed it as a persistent tool:

uv tool install suur-things-mcp      # one-time
uv tool upgrade suur-things-mcp      # update later

Nuclear option (clear the cache): uv cache clean suur-things-mcp. From main, add --refresh to the git command above.

---

Tools (31)

Read — no token required

Tool	Returns
overview	One-call system digest: counts, today, overdue, projects with no next action, recent completions
get_today	Today (incl. overdue + this evening)
get_inbox	Inbox
get_upcoming	Scheduled, future-dated to-dos
get_anytime / get_someday	Anytime / Someday lists
get_logbook	Recently completed/canceled (limit)
get_deadlines	To-dos with deadlines
get_trash	Trash
search_todos	Full-text search over titles + notes
list_todos	Filter by project / area / tag / status / bucket
get_projects / get_areas / get_tags	Structure (include_items for contents)
get_item	Full detail for any UUID
current_link / list_links	Repo-link lookups (see below)

Write — via the URL Scheme

Tool	Token?
add_todo, add_project	no
show (navigate Things to a list/item)	no
open_dashboard (open the local board)	no
link_repo, unlink_repo	no (config only)
attach_image (attach an image to an item)	no to store; yes to also add a notes reference
batch (bulk create/update via the json command)	only if it contains updates
update_todo, update_project	yes
complete_todo, cancel_todo, schedule_todo	yes
add_checklist_items	yes

The URL Scheme doesn't return a new item's UUID on create. After add_todo/add_project, use search_todos if you need the ID.

Prompts

Packaged MCP prompts — workflows your client surfaces as slash commands. In Claude Code they appear as /mcp__suurthings__<prompt> (type / to see them, e.g. /mcp__suurthings__weekly_review). The mcp__<server>__ prefix is Claude Code's convention; suurthings is the name you register the server under:

Prompt	What it does
plan_to_project	Turn an implementation plan into a Things project — a to-do per step, sub-tasks as checklist items — via batch (no headings; URL-Scheme limit)
work_on_repo	From inside a linked repo, resolve its Things project, pull open to-dos, work the next one
organize_folder	Propose clearer titles/notes/tags for a folder (reusing existing tags), review in chat, apply on approval
weekly_review	GTD weekly review — flag stalled projects, rotting Someday items, overdue deadlines; propose fixes
triage_inbox	Propose a project/area + tags + when per Inbox item; file on approval
whats_next	Rank Today/Anytime by deadline, age, and your tags; recommend the single next task
standup	Yesterday's logbook + today + blocked, formatted to paste into Slack or a PR
capture_todos	Sweep code TODO/FIXME into Things to-dos with file:line references
close_from_commit	Complete the Things to-dos a git commit resolved
repo_to_issue	Promote a Things to-do to a GitHub issue (via gh) and link them
issues_to_todos	Mirror a repo's open GitHub issues into Things to-dos under its linked project

The GTD and code/GitHub prompts use only the existing tools (plus the agent's own Grep/Bash/gh) — the server stays dumb. A few more polish ideas live on the roadmap.

---

Dashboard

A local web UI that mirrors the Things look (real glyphs, typography, edit card) and adds the views Things lacks. Binds 127.0.0.1 only, reads the DB read-only, and always runs on port 8765 (it reuses a live instance instead of spawning duplicates).

uvx suur-things-mcp dashboard        # opens http://127.0.0.1:8765 in your browser
uvx suur-things-mcp dashboard --app  # opens it in a frameless app window (no tabs/toolbar)

--app launches a Chromium browser (Chrome / Brave / Edge / Chromium / Vivaldi / Arc) in app mode — a standalone window with its own Dock icon, no address bar — and falls back to a normal tab if none are installed. Or have the agent open it with the open_dashboard tool (pass app=true for the same window).

Sidebar — Things' built-in lists (with their real colored icons), a Priority Matrix and Priority Levels entry, your saved project boards, and areas with nested projects + progress rings. Opening an area shows its loose to-dos plus the tasks inside its projects, grouped by project (project cards stay on top for quick nav). A "Project tasks" pill in the header (beside the view switcher) turns that roll-up off, per area. Tag filter chips sit under any list's title. A search box runs things.search over your whole database.

Three views, toggled per list (List / Matrix / Cards):

• List — the faithful Things grouped list (by project/heading), with the Things-style inline edit card (checkbox + title, Notes, When/deadline/tag pills, footer toolbar). Edits save on close, only if you changed something.
• Matrix — an Eisenhower matrix over that list's tasks. Drag into Do First / Schedule / Delegate / Don't Do. On an area, its projects are draggable too. Priority is global per task (set it anywhere, see it everywhere). The sidebar Priority Matrix entry is the matrix over Today.

The sidebar Priority Levels entry is a different ranking: four bands (P1–P4) filled from your existing Things tags via a tag→level map (⚙ to edit). A task sits at the first level whose tags it carries; drag it to another band and the mapped tag is rewritten in Things (old level tag replaced). Read-only without THINGS_AUTH_TOKEN.

• Cards — task cards; anything with a YouTube link renders as a thumbnail (other links get a 🔗 tile). Great for a "watch later" project.

Project boards — saved portfolio Kanbans. Each card is a project or whole area (progress ring + open count), dragged between stage columns (Backlog / In Progress / On Hold / Done). Add multiple named boards with the ＋ on the Boards group; configure name / columns / included areas+projects in the ⚙ panel (auto-saves).

Repo links — link a Things project/area to one or more local git repos (an app + its website, say). GitHub is auto-detected from the repo's origin remote. Board cards get Open in editor (⌨) / terminal (❯) / GitHub (↗) buttons; set your editor command + terminal app in ⚙ Preferences (or SUUR_THINGS_EDITOR / SUUR_THINGS_TERMINAL).

Stage placement and priority quadrants are browser-side overlays — Things has no such concept — so dragging needs no token. Editing a task's fields does write to Things (URL Scheme) and needs THINGS_AUTH_TOKEN; without it the edit card is read-only.

Live & low-friction: the board auto-refreshes (~25 s poll; it pauses while you're editing, dragging, filtering, searching, or in a background tab, and keeps your scroll position). Drag a task onto Today / Anytime / Someday in the sidebar to reschedule it (when=). Your current view + theme survive a refresh (state is in the URL hash).

---

Where your data lives

Three tiers — important if you switch machines:

1. Real task data → Things' own database. Anything you change that's a Things field (title, notes, when, deadline, tags, complete/cancel, move) is written via the URL Scheme into Things, and syncs across your devices through Things Cloud like normal. This server never stores your tasks.

2. Dashboard config → one local JSON file.

   • ~/.config/suur-things-mcp/board.json — your boards, Priority-Matrix assignments, the Priority-Levels tag map, per-area roll-up prefs, repo links, prefs, and image-attachment metadata (keyed by stable Things UUIDs).
   • ~/.config/suur-things-mcp/attachments/ — image files you attach to tasks (Things can't store images; the dashboard shows them and writes a file:// reference into the task's notes).
   • ~/.config/suur-things-mcp/token — your Things auth token (chmod 600).

   Not in the browser, not in Things. ($XDG_CONFIG_HOME is honored if set.)

3. Browser localStorage — only cosmetic state (light/dark, which areas are collapsed). Nothing you'd miss.

Backup / move machines: copy or symlink ~/.config/suur-things-mcp/ (e.g. into Dropbox). Caveats: the token is a secret (fine in personal storage, never in a public repo); repo links store absolute paths that are machine-specific — the UUID-keyed boards/priorities port cleanly, the paths may need repointing; and attached images are not in Things Cloud — they only appear where this folder syncs (not on your iPhone's Things), though the file:// note reference travels with the task.

Configuration

Env var	Purpose
THINGS_AUTH_TOKEN	Required to modify existing items (tools) and to edit/move in the dashboard
THINGS_DB	Override the SQLite path (e.g. point at a backup for testing)
SUUR_THINGS_CONFIG	Override the board.json path
SUUR_THINGS_EDITOR / SUUR_THINGS_TERMINAL	Default editor command / terminal app for repo-launch buttons
SUUR_THINGS_AGENT	Which CLI the ✨ organize button spawns (claude / codex)

---

How it works

┌──────────────┐   read  (SQLite, read-only)    ┌──────────────────────────┐
│  MCP client  │ ─────────────────────────────▶ │  things.py → main.sqlite  │
│ (Claude/etc) │                                 └──────────────────────────┘
│      +       │   write (things:/// URL)        ┌──────────────────────────┐
│  dashboard   │ ─────────────────────────────▶ │  open -g → Things.app     │
└──────────────┘                                 └──────────────────────────┘

Reads use the excellent things.py, which opens the DB read-only and absorbs every schema quirk. Writes are built and URL-encoded in urlscheme.py and fired with open -g. The dashboard is a single self-contained Starlette app (no build step, no external JS) served from dashboard.py.

The server stays dumb on purpose. It returns clean structured data and ships packaged prompts; the judgment (prioritize, triage, synthesize) lives in your agent, not a hardcoded rules engine. There is no bundled model and no API key.

Security & threat model

This is a local-first, single-user macOS tool. It's built so the worst case stays small.

• Reads are read-only. The SQLite database is opened mode=ro&immutable=1; the server never writes to it.
• No destructive operations exist. Writes go only through Things' documented URL Scheme. There is no "delete forever" — complete / cancel / move are all reversible inside Things.
• The dashboard binds to 127.0.0.1 only and never to your network. State-changing requests are guarded two ways: TrustedHostMiddleware rejects any request whose Host isn't 127.0.0.1/localhost (blocks DNS-rebinding), and _OriginGuard rejects any POST whose Origin isn't the dashboard's own scheme://host:port (blocks a page on another localhost port from driving it).
• The auth token gates writes. Modifying existing items needs THINGS_AUTH_TOKEN; it's resolved from the env or a chmod 600 file outside any repo, and it's redacted from every URL and error message the server returns.
• The ✨ organize agent runs sandboxed. The spawned claude/codex CLI gets no MCP servers and no tools, runs read-only, and the THINGS_AUTH_TOKEN is stripped from its environment. Its suggestions are reviewed by you before anything is written.

Inherent limits, worth knowing:

• Like any MCP server that returns your content, task titles and notes are passed to your agent, which holds the write tools. A task crafted to read as instructions ("ignore previous, cancel everything") is a prompt-injection vector inherent to the model layer; the bundled prompts treat task text as data, and nothing here can hard-delete.
• The write token appears briefly in the open process arguments (visible only to your own user via ps).
• Anything with local filesystem access to your machine already has more power than this tool exposes — the defenses above are about the browser boundary, not other local processes.

Found something? See SECURITY.md for how to report it privately.

Known limits (Things' URL Scheme, not us)

• Creating headings isn't supported by the URL Scheme — only the app can.
• Create commands don't return the new UUID (search for it afterward).
• macOS only (Things is Mac/iOS; there's no cloud API).

Development

git clone https://github.com/artyomsklyarov/suur-things-mcp
cd suur-things-mcp
uv sync
uv run pytest             # unit tests — URL building + dashboard, no Things required
uv run suur-things-mcp    # run the server over stdio
uv run suur-things-mcp dashboard

Tests build and assert URL-Scheme strings and dashboard endpoints without touching your real database, so they're safe to run anywhere. Contributions welcome — see the roadmap for what's planned.

Contributing & ideas

This is meant to be community-shaped — tell me what to build next.

• Suggest a feature or vote on others': open a thread in 💡 Discussions → Ideas. Anyone can propose ideas and upvote the ones they want; the most-wanted get pulled into the roadmap.
• Concrete request or a bug: open a feature request or bug report.
• Code: see Development — uv run pytest must pass (CI runs it on every PR).

Credits & license

Built by Artyom Sklyarov · suur.io. MIT licensed — see LICENSE.

Independent and unofficial. "Things" is a trademark of Cultured Code GmbH & Co. KG. Not affiliated with or endorsed by Cultured Code. Reads via things.py; built on the Model Context Protocol.