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.

This avoids direct database writes by the integration. URL Scheme actions still change your tasks, so review proposed changes and verify their outcomes.

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. There is no telemetry or bundled LLM. Optional agent/provider calls, GitHub activity and external thumbnails can use network services.

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 integration therefore avoids direct database mutation; this is not a guarantee that every requested task change is harmless or reversible.

✨ 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; a named Schedule dialog also supports keyboard time/duration changes and unscheduling.)
• 🧘 Calm Today — start a reviewed proposal for a single next action, a short list and possible deferrals. 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.

The package is free, local and open source, with no hosted dashboard, task account or telemetry. Optional organizer workflows use your own agent account/provider and may have their own usage costs.

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 proposes one next action and a short list; triage proposes Inbox filing decisions. 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 (32)

Read — no token required

Write — via the URL Scheme

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:

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 prefers port 8765 (it reuses a compatible live instance; a foreign process can require another available port).

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)
uvx suur-things-mcp dashboard --install-service   # always-on: launchd KeepAlive service at login
uvx suur-things-mcp dashboard --uninstall-service # remove the service again

--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.

Five views, toggled per list (List / Matrix / Levels / Cards / Timeline):

• 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.

Keyboard and narrow windows — dialogs contain/return focus, sidebar/task actions are keyboard reachable, and native destination selectors supplement advanced drag actions. Windows <=800px use full-width content with menu navigation. ?compact=0 and ?placement=0 are diagnostic fallbacks.

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 (5 s change-cursor 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

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 handles supported schema details. 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 canonical "delete forever" tool; complete/cancel/move still change tasks and should be reviewed. Local attachment removal is an explicit dashboard feature.
• 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. Claude disables tools/MCP; Codex uses a best-effort read-only sandbox. Both run in an empty temporary directory with Things auth and unrelated secrets stripped; provider authentication is retained. 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

Canonical handoff: CONTEXT.MD (product), SPEC.MD (technical), STATUS.MD (verified state), TODO.MD (user checks), PLAN.MD (unfinished work).

For complete fixture verification, synthetic screenshots and non-destructive config recovery, see Development verification. Run .venv/bin/python .autoloop/scripts/verify.py local-check with the dev environment and Chromium installed; this stricter gate rejects skipped tests.

git clone https://github.com/artyomsklyarov/suur-things-mcp
cd suur-things-mcp
uv sync --dev
uv run playwright install chromium
.venv/bin/python .autoloop/scripts/verify.py local-check  # complete fixture gate
uv run suur-things-mcp    # run the server over stdio
uv run suur-things-mcp dashboard

The strict fixture gate uses a disposable synthetic database/config and mocked mutation/model calls. Ordinary pytest can skip environment-dependent checks; it is not equivalent to the complete gate. 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.