Things3

This MCP server enables you to manage Things3 data through the Model Context Protocol. You can create projects and todos, view inbox and today’s tasks, search across todos, and mark items as completed—all via MCP client requests. It’s designed for reliable operation with robust error handling, secure URL handling, and seamless AppleScript integration on macOS.

How to use

You connect to the Things3 MCP server from your MCP client and perform actions by selecting the Things3 server as your target. Use operations to create projects and todos with rich metadata, list items from the inbox, today’s list, or all projects, and search or complete tasks by title or content. The server validates Things3 availability before performing actions and handles encoding safely for all parameters.

Key capabilities you can use through your MCP client include creating a Things3 project with optional notes, area, due date, and tags; creating a to-do with optional checklist, tags, and associated project; viewing the inbox, projects, and today’s todos; completing a to-do by title; and searching todos by title or content. Each operation returns structured results with statuses and relevant metadata.

How to install

Prerequisites you need before installation:

• macOS with Things3 installed and AppleScript permissions granted when prompted

• Python 3.8+ installed

• Things3 must be running for real-time operations

# Step 1: Clone the MCP Things3 server repository
git clone <repository-url>
cd mcp-things3

# Step 2: Install the server in editable mode
pip install -e .

# Step 3: Run the MCP Things3 server (see the stdio config in configuration)
# The server executable will be available as mcp-server-things3
mcp-server-things3

Configuration and usage notes

The server operates with a straightforward stdio configuration. The executable to start is provided as an installed console script, and you pass no additional arguments unless your environment requires them. Ensure Things3 is running and accessible before initiating operations.

{
  "mcpServers": {
    "things3": {
      "type": "stdio",
      "name": "things3",
      "command": "mcp-server-things3",
      "args": []
    }
  }
}

Security and reliability

The server includes input sanitization for safety with AppleScript, proper URL encoding for special characters and Unicode, validation to confirm Things3 is available before performing operations, and graceful error recovery to handle AppleScript or system issues.

Troubleshooting

If Things3 is not available, ensure it is installed and running and that AppleScript permissions are granted. If you encounter an AppleScript execution error, verify macOS security settings allow AppleScript and ensure Things3 has required accessibility permissions. For URL encoding issues, check logs for encoding problems and confirm inputs are correctly escaped.

Development and testing

Development and testing steps assume you are running locally. You can run tests with Python and observe logs for debugging as needed.

Notes about tools and endpoints

The server exposes operations to view inbox items, view projects, view today’s todos, create Things3 projects, create Things3 todos, complete todos by title, and search todos by a query. These capabilities are available through your MCP client as distinct operations.

Available tools

create-project

Create a new Things3 project with optional notes, area, start time, deadline, and tags.

create-todo

Create a new Things3 to-do with optional notes, start time, deadline, checklist, tags, and assignment to a project or list.

view-inbox

List all to-dos in the Things3 inbox with due dates and scheduling information.

view-projects

List all projects in Things3 with their titles.

view-todos

List today’s to-dos with associated metadata.

complete-todo

Mark a to-do as completed by searching for its title.

search-todos

Search for todos by title or content and return matching results.