things-app

This MCP server provides a local Python-based integration for Things.app on macOS. It exposes a set of tools that wrap Things actions (such as creating, updating, or querying Things items) and translates them into the Things URL scheme (things:///…) or AppleScript-backed operations. The server runs over FastMCP conventions using stdio transport by default, making it compatible with Codex MCP workflows and the FastMCP CLI. You can use the built-in “health” tool to verify the service is responsive, and you can perform a range of Actions such as things_capabilities, things_add_todo, things_update_project, things_import_json, and more. Some read operations (things_read_todos, things_read_projects, things_read_areas, things_read_headings, etc.) execute via AppleScript where applicable, and others dispatch through Things URL scheme calls. The tools are documented in the README, and you can invoke them using the generic tool endpoint or the provided script helpers (see the examples in the README).

Prerequisites:

• macOS with Things.app installed
• Python 3.13+ (and uv if using the development workflow)
• Access to the Things app via AppleScript (Automation permissions required)

Installation steps:

1. Ensure prerequisites are installed:

   • macOS with Things.app
   • Python 3.13+ (install via pyenv, Homebrew, or your preferred method)
   • uv (for development workflow if needed): pip install uv

2. Install dependencies and set up environment (if using uv/virtualenv):

   • python -m venv .venv
   • source .venv/bin/activate
   • pip install -r requirements.txt (if a requirements file is provided)

3. Run the server (as defined in mcp_config):

   • python app/server.py

4. Verify endpoints with the FastMCP CLI, for example:

   • make run-http (if using the HTTP transport for testing)
   • make list-http
   • make call TOOL=health

5. Optional: configure an auth token for update commands by exporting THINGS_AUTH_TOKEN or passing via ARGS_JSON to update tools.

Tips and caveats:

• Update operations require an auth token. The token can be supplied via THINGS_AUTH_TOKEN env var, an explicit auth_token in ARGS_JSON, or stored in macOS Keychain. The README documents the resolution order and token handling.
• For end-to-end safety during testing, use make smoke-json which runs with THINGS_MCP_DRY_RUN=1 to skip launching actual Things URLs.
• macOS Automation permissions are required for AppleScript-based reads. If read calls fail due to permissions, grant terminal or Codex access under System Settings > Privacy & Security > Automation and re-run tests.
• The server exposes a broad set of tools (health, things_capabilities, things_add_todo, things_update_project, things_import_json, things_read_todos, things_find_todos, things_read_projects, things_read_areas, things_read_headings, things_auth_* variants, and more). Use things_capabilities to discover what’s implemented.
• When using things_import_json, the payload must follow the lightweight validation described in the README; update operations require a valid auth token when necessary.
• For local testing, the default host/port can be overridden via the provided Makefile examples (HOST=127.0.0.1, PORT=8123) and MCP URL adjustments for http transport tests.