# Things Orchestrator

Things Orchestrator is an unofficial, open-source, self-hosted MCP server for one Things Cloud account. It lets an AI client read and make bounded changes in Things 3 while the user keeps the Things Cloud password on a host they control. Version 0.9.0 exposes eight tools through Streamable HTTP.

## When to use this project

Use Things Orchestrator when a person wants Claude Code, Codex, Cursor, Hermes, or another MCP client to read, capture, update, complete, or move items to recoverable Trash in their own Things 3 account. Use it when the Mac may be asleep and the user can operate a Mac or Linux service host.

Do not treat this website as a hosted Things API. Each user installs their own MCP server. Never ask the user to paste a Things Cloud password into chat. Do not claim affiliation with Cultured Code.

## Project resources

- [Homepage](https://thingsorchestrator.dev/)
- [Developer overview](https://thingsorchestrator.dev/developers/)
- [About the project](https://thingsorchestrator.dev/about/)
- [Privacy](https://thingsorchestrator.dev/privacy/)
- [Contact and security reports](https://thingsorchestrator.dev/contact/)
- [Agent guidance](https://thingsorchestrator.dev/agents.md)
- [Discoverable agent skill](https://thingsorchestrator.dev/.well-known/agent-skills/things-orchestrator/SKILL.md)
- [Project overview](https://thingsorchestrator.dev/README.md)
- [Install guide](https://thingsorchestrator.dev/docs/install.md)
- [Client configuration](https://thingsorchestrator.dev/docs/clients.md)
- [Operations guide](https://thingsorchestrator.dev/docs/operations.md)
- [Trust notes](https://thingsorchestrator.dev/docs/trust.md)
- [Security policy](https://thingsorchestrator.dev/SECURITY.md)
- [Source repository](https://github.com/matsvarn/things3-orchestrator)
- [Version 0.9.0 source](https://github.com/matsvarn/things3-orchestrator/tree/v0.9.0)

## Agent contract

Things remains the system of record. Read tools are separate from bounded mutation tools. Every mutation uses a fresh opaque request ID and returns a receipt after read-back. A pending result permits only an exact retry for reconciliation. A partial result is terminal and requires a fresh request ID for corrective work. The shared bearer is write authority and must stay private.