Things MCP Server

A Python CLI MCP (Model Context Protocol) server for Things 3, enabling programmatic access to todos and projects, including filtering by due date. Designed for automation, scripting, and integration with other tools.

Features

• Query all todos and projects from Things 3
• Filter todos by project or due date (YYYY-MM-DD)
• Clean, type-safe, and test-driven codebase
• CLI installable and easy to run
• Automation via justfile (run, test, lint, format, upgrade, etc.)

Installation

uv pip install --break-system-packages .

Usage

Start the MCP server:

things-mcp

Or, for development:

just run

Querying Todos

Example request to get all todos:

{"method": "get-todos"}

Example request to get todos due today:

{"method": "get-todos", "params": {"due_date": "2025-06-24"}}

Querying Projects

{"method": "get-projects"}

Development

• Run tests: just test
• Lint: just lint
• Format: just format
• Upgrade deps: just upgrade
• Add pre-commit hooks: just precommit
• Clean: just clean

Contributing

See CONTRIBUTING.md for guidelines. Please read our Code of Conduct.

Changelog

See CHANGELOG.md for release history.

Security

See SECURITY.md for reporting vulnerabilities. Contact: [[email protected]]

License

Apache License, Version 2.0. See LICENSE.