mcp -things

This MCP server enables Claude and other AI assistants to interact with Things 3 for natural language task management. It exposes a set of MCP tools for managing todos, projects, areas, and lists within Things 3, including creating, reading, updating, and deleting items, as well as query-based operations like getting due or upcoming tasks. The server runs as a Python module (things_mcp) and can be configured to control logging, timeouts, and AppleScript permissions required by Things 3. After starting the server, clients can send MCP calls to perform operations such as adding a todo with metadata, retrieving items by project or list, and performing date-range searches. Use Claude Desktop or another MCP client to issue these tool calls and receive structured results.

Prerequisites:

• macOS with Things 3 installed
• Python 3.8+ installed in a virtual environment

Option 1 — From PyPI (Recommended):

1. Create and activate a virtual environment: python3 -m venv venv source venv/bin/activate # macOS/Linux
2. Install the package: pip install mcp-server-things

Option 2 — From Source (Development):

1. Clone the repository: git clone https://github.com/ebowman/mcp-server-things.git cd mcp-server-things
2. Create and activate a virtual environment: python3 -m venv venv source venv/bin/activate # macOS/Linux
3. Install dependencies: pip install -r requirements.txt
4. Install in development mode: pip install -e .

Configuration and usage after install:

• Ensure Things 3 is installed and accessible from AppleScript.
• Set THINGS_MCP_LOG_LEVEL and other options as needed via environment variables or a .env file.
• Run the server using: python -m things_mcp

If using Claude Desktop, add the MCP server configuration under the appropriate mcpServers entry (see README for examples).

Tips and common considerations:

• Ensure AppleScript permissions are granted for Things 3 access on macOS.
• Configure environment variables for log level, timeout, and tag handling as needed (e.g., THINGS_MCP_LOG_LEVEL, THINGS_MCP_APPLESCRIPT_TIMEOUT, THINGS_MCP_AI_CAN_CREATE_TAGS).
• When developing locally from source, remember to set PYTHONPATH if you’re importing from the src directory during runtime.
• Use the provided command-line options (e.g., --debug, --env-file, --health-check) to diagnose connectivity and health of the MCP server.
• For Claude Desktop, prefer the full path to the Python executable in your virtual environment when configuring the mcpServers entry.