Things3 MCP Server: Tasks, Projects, Tags

Overview

This MCP (Model Context Protocol) server exposes Things 3 model objects — tasks, projects and tags — over a local HTTP API on macOS. It implements the MCP pattern used by Things 3 so external scripts and services can read and modify your Things database in a structured way. The server is intended for developers who want automated access to their TODO items for synchronization, integration, backups, or custom workflows.

Running the MCP server on your Mac gives programmatic, REST-like access to Things 3 data without manual exporting. That makes it easier to build integrations (scripts, webhooks, third‑party automations) that create tasks, reorganize projects, update tags, or export the current state to other tools.

Features

• Read and list Things 3 tasks, projects and tags
• Create, update and delete tasks programmatically
• Project and tag enumeration for building integrations
• Local HTTP API on macOS (runs against your local Things database)
• Simple JSON API designed for automation and scripting
• Configuration file for port, authentication, and database paths

Installation / Configuration

The project runs on macOS. Typical installation steps (from source):

# Clone the repository
git clone https://github.com/urbanogardun/things3-mcp.git
cd things3-mcp

# Create and activate a Python virtual environment (example)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Copy and edit the example configuration:

cp example-config.json config.json
# Open config.json and set:
# - port: HTTP port to listen on (e.g. 3000)
# - auth_token: simple bearer token for API access
# - things_db_path: path to Things 3 database (if required)

Start the server (example):

python -m things3_mcp.server --config config.json
# or
./run.sh --config config.json

Optional: Docker (if supported by the repository)

docker build -t things3-mcp .
docker run -p 3000:3000 --volume ~/Library/Group\ Containers/:/data things3-mcp

Security note: The server typically runs on localhost and you should protect it with an auth token if you expose it beyond your machine.

Available Resources

• GitHub repository: https://github.com/urbanogardun/things3-mcp
• API endpoints (common surface):
  • GET /v1/tasks — list tasks
  • GET /v1/projects — list projects
  • GET /v1/tags — list tags
  • GET /v1/tasks/:id — fetch a single task
  • POST /v1/tasks — create a task
  • PATCH /v1/tasks/:id — update a task
  • DELETE /v1/tasks/:id — delete a task

Example curl requests (replace AUTH_TOKEN and base URL if configured):

# List tasks
curl -H "Authorization: Bearer AUTH_TOKEN" http://localhost:3000/v1/tasks

# Create a task
curl -X POST -H "Authorization: Bearer AUTH_TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Buy coffee","notes":"Roast: medium","project_id":"proj-123","tags":["errand"]}' \
  http://localhost:3000/v1/tasks

API Table

Use Cases

• Automated sync to other TODO systems: Periodically read Things 3 tasks and push changes to a secondary system (e.g., a team tracker or personal knowledge base).
• Scripted task creation: Create tasks from scripts, command-line tools, or incoming emails (e.g., a script that turns starred messages into Things tasks via the MCP server).
• Bulk edits and migrations: Use the API to rename a tag across all tasks or to move multiple tasks into a new project in a single script.
• Backups and exports: Export tasks/projects/tags to JSON for archival, diffing, or importing into other tools.
• Home automation and notifications: Trigger automations (e.g., when a task is due, send a notification or create related calendar events) by watching Things via the MCP API.

Notes for Developers

• The server is designed for local development and automation on macOS where Things 3 is installed.
• Respect Things 3 and macOS privacy and file access: the server may need permission to access Things data if the database is protected by macOS privacy controls.
• Check the repository README and example config for implementation specifics, dependency versions and any supported authentication mechanisms.
• If you extend the server, prefer idempotent operations for