mcp-things3

This MCP server provides a Things3 integration, enabling you to manage Things3 projects and todos through the MCP protocol. You can view items in the Things3 inbox or today’s list, create new projects and to-dos with rich metadata (including notes, areas, deadlines, and tags), search for todos by title or content, and mark tasks as completed by title. The server is designed to work with Claude AI, allowing you to issue natural-language commands like creating a project with a deadline, adding a todo with a checklist, showing today’s tasks, marking a task as completed, or searching for related todos. The available operations are organized into view, creation, and management actions, and the server includes robust error handling and safe AppleScript integration for macOS.

Prerequisites:

• macOS with Things3 installed
• Python 3.8+
• Things3 running (for real-time operations)

Installation steps:

1. Clone the repository: git clone <repository-url> cd mcp-things3

2. Install in editable mode: pip install -e .

3. Run or configure the server as an MCP service named mcp-server-things3. For client configuration examples, see the included documentation. The server will be available as the executable mcp-server-things3 when installed via the provided setup.

4. Optional: Run tests during development: python test_things3.py

Prerequisites recap: Ensure macOS-compatible environment with Things3 installed and accessible, and Python 3.8+ available to install and run the server in development or production. Follow the repository’s README for any project-specific setup steps or environment configurations.

Notes and tips:

• If you encounter issues with Things3 not being available, verify that Things3 is running and that AppleScript permissions are granted.
• The server performs URL encoding handling for special characters and Unicode; if you see encoding issues, check the logs for URL construction details.
• The integration places emphasis on safe AppleScript interaction to prevent JSON-based string concatenation pitfalls.
• For debugging, you can enable verbose logging and run the main server entry point as demonstrated in the README's debugging section.
• The MCP client configuration example shows how to reference the server; ensure your client’s mcpServers block uses the same key (things3) and the correct command/args as installed on your system.