Things Safe MCP
# Things Safe MCP
An unofficial MCP server for Things 3 that uses only integration methods
Cultured Code documents as safe:
- AppleScript for reads and normal task edits.
- The Things URL scheme for checklist edits.
It never reads or writes the Things database, app-support files, or Things
Cloud credentials. It is macOS-only and requires Things 3.
## Install
Install [uv](https://docs.astral.sh/uv/), then register the server with your MCP
client. For Codex:
```sh
codex mcp add things -- uvx --from git+https://github.com/jasongibby/things-safe-mcp things-safe-mcp
```
For another stdio MCP client, use:
```json
{
"mcpServers": {
"things": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/jasongibby/things-safe-mcp",
"things-safe-mcp"
]
}
}
}
```
Start Things once before the first request. macOS will ask for permission for
your MCP host to automate Things.
## Checklist token
Only checklist edits need a Things URL authorization token. In Things, open
**Settings → General → Enable Things URLs → Manage**, generate a token, and
provide it to the server as `THINGS_AUTH_TOKEN` through your MCP client's secure
environment configuration. Do not commit or share it.
All other operations work without a token.
## Tools
- Read Inbox, Today, Upcoming, Anytime, Someday, projects, project tasks, and
directly tagged tasks.
- Search task titles and notes.
- Create tasks.
- Edit titles, notes, tags, status, schedule, and project assignment. Pass an
empty project ID to detach a task.
- Replace, append, or prepend checklist items.
## Safety and privacy
Cultured Code lists AppleScript and the Things URL scheme as safe connection
methods. This server passes user input as process arguments rather than
interpolating it into AppleScript source.
Your MCP client and AI provider can see task data returned by the server. Review
their privacy policies before use. This project is not affiliated with or
endorsed by Cultured Code.
- [Third-Party AI Tools and Things](https://culturedcode.com/things/support/articles/5510170/)
- [Things AppleScript Commands](https://culturedcode.com/things/support/articles/4562654/)
- [Things URL Scheme](https://culturedcode.com/things/support/articles/2803573/)
## Development
```sh
uv sync
uv run python -m unittest discover -s tests -v
```
Tests mock all external processes and never access Things.
## License
MIT
TDQS
Scored across 12 tools
Each tool targets a distinct resource or view: separate list views (inbox, today, upcoming, anytime, someday), project tasks, projects, search, tags, and CRUD operations. No two tools overlap in purpose, and the descriptions clearly differentiate them.
All tools follow a consistent verb_noun pattern in snake_case (e.g., get_inbox, add_todo, update_checklist). The verbs are limited to get, search, add, and update, and nouns clearly indicate the target entity, making the naming predictable and uniform.
12 tools is well within the typical 3-15 range for a focused server. Each tool covers a distinct feature of the Things app, and there is no redundancy or bloat; the count feels proportional to the domain's complexity.
The set covers viewing multiple lists, projects, search, tags, and adding/updating todos and checklists, but misses common lifecycle operations like deleting or completing todos, and does not provide project creation or deletion. These are notable gaps for a task management server, though most core workflows are supported.