Things 3CAUTION
A rich MCP server for Things
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://www.python.org/downloads/) [](LICENSE) [](https://www.apple.com/macos/)
A Model Context Protocol (MCP) server that connects Claude and other AI assistants to Things 3 for natural language task management.
Why this server?
Writes go through AppleScript, not the Things URL scheme, which is what enables delete_todo, move_record/bulk_move_records, remove_tags, real IDs returned synchronously, and no Things auth token — the trade-off is a one-time macOS Automation permission prompt on first write. Operationally it also ships built-in doctor diagnostics, config --write client setup, context-optimized response modes for large databases, and 1300+ unit tests.
hald/things-mcp is a solid, lighter URL-scheme-based alternative — several of its ideas (Someday-project filtering, tag usage reporting, .mcpb packaging) are adopted here too. See docs/COMPARISON.md for the detailed matrix.
Prerequisites
- macOS 12+
- Things 3 installed and opened at least once
- uv (
brew install uv) - macOS will ask for Automation permission for Things 3 on the first write — that's expected (AppleScript is what enables delete/move operations other servers lack).
Install
Claude Desktop
Option A: One-click `.mcpb`
Download the latest .mcpb file from the releases page and double-click it to install into Claude Desktop.
The bundle launches the server via uvx, so uv must be installed and on PATH (brew install uv). The generated config pins uv's managed Python (--python-preference only-managed) so a stray Intel/Rosetta Python on your PATH can't break the i
0ddbaeb00e96OBSERVED · 2026-10-08Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.
claude mcp add mcp-server-things -- uvx mcp-server-things
{
"mcpServers": {
"mcp-server-things": {
"command": "uvx",
"args": [
"mcp-server-things"
]
}
}
}Exposed tools (11)
9 read · 1 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
context_stats | read | Get context usage statistics and optimization insights. |
create_tag | write | Create a new tag. Note: For human use only, AI should ask users to create tags. |
delete_todo | destructive | Trash a to-do or project by ID (moves it to Things |
get_server_capabilities | read | Get server capabilities, features, API coverage, and optimization settings. Returns structured information about available tools, response modes, and performance characteristics. |
get_tagged_items | read | Get todos with a specific tag. |
get_tags | read | Get all tags with item counts or full items. Use include_items=true for full item lists. |
get_todo_by_id | read | Get a specific Things item by its ID. |
get_todos | read | Get todos with context-aware response optimization. Supports mode parameter (auto/summary/minimal/standard/detailed/raw) and optional project filtering. Use mode= |
get_usage_recommendations | read | Get usage recommendations for efficient MCP operations. Optionally specify an operation name for targeted guidance. |
health_check | read | Check server health and Things 3 connectivity. |
queue_status | read | Get operation queue status and statistics. |
Trust audit
CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (1 observation(s))
- Network
- declared (1 observation(s))
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (11)
{"_type":"issue","id":"hq-dzy.5","title":"Add HTTP transport option (THINGS_MCP_TRANSPORT=stdio|http, HOST, PORT) for parity and as the TCC workaround","description":"INPUT: FastMCP 3.x mcp.run(transpdelete_todo
mod = importlib.import_module(module_name)
- **Optional HTTP transport** - `THINGS_MCP_TRANSPORT=stdio|http` (default `stdio`), `THINGS_MCP_HOST` (default `127.0.0.1`), and `THINGS_MCP_PORT` (default `8000`) env vars, plus matching `--transpor
claude mcp add --transport http things http://127.0.0.1:8000/mcp
(`npx mcp-remote http://127.0.0.1:8000/mcp`), or point Claude Code directly
claude mcp add --transport http things http://127.0.0.1:8000/mcp
fastmcp, pydantic, python-dateutil, dateparser, pytest, pytest-asyncio, pytest-timeout, black
- No elevated privileges needed
curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
- **Things URL-scheme auth token no longer requires a server restart to pick up a newly-added or fixed token file, and its failure/status is now diagnosable** (bead hq-wsa.4). `AppleScriptManager` pre
Gates applied: no_behavioural_pass.
0ddbaeb00e96full audit observations/trust-audit/mcp-server/ebowman__things-3-1.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-08 | 0ddbaeb00e96 | CAUTION | B | 89 | first audit |
Questions
What is the Things 3 MCP server?
A rich MCP server for Things
What tools does Things 3 expose?
11 in total: 9 read-only, 1 that write, and 1 that can delete or overwrite (delete_todo). Every one is listed on this page with its risk.
Is Things 3 safe to connect to an agent?
With care. The audit graded it B (89/100) and found 11 things worth knowing before you trust this server, listed below with the exact line each was found on. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does Things 3 need?
No credential environment variables were found in its source, so it appears to need none.
How current is this page?
The grade is for one exact copy of the source (0ddbaeb00e96), read on 2026-10-08. The repository is watched and re-audited when it changes.