Things3 MCP server

This MCP server provides a powerful interface to Things3, allowing you to create, manage, and search tasks and projects through the Model Context Protocol. It integrates with Claude AI and other MCP clients to enable natural language interaction with your task management system.

Installation

Prerequisites

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

Install the Server

1. Clone this repository:

   git clone <repository-url>
   cd mcp-things3
   

2. Install using pip:

   pip install -e .
   

3. The server will be available as mcp-server-things3

Configuration

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop config):

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

Things3 Setup

1. Ensure Things3 is installed and running
2. Grant necessary permissions when prompted for AppleScript access
3. The server will validate Things3 availability before operations

Available Tools

View Operations

View Inbox

View all todos in the Things3 inbox.

• Parameters: None
• Returns: List of inbox todos with due dates and scheduling info

View Projects

View all projects in Things3.

• Parameters: None
• Returns: List of all projects with their titles

View Todos

View all todos in today's list.

• Parameters: None
• Returns: List of today's todos with metadata

Creation Operations

Create a Project

Creates a new project in Things3.

• Required: title (string)
• Optional:
  • notes (string)
  • area (string)
  • when (string) - Date/time to start
  • deadline (string) - Due date
  • tags (array of strings)

Example:

{
  "title": "Website Redesign",
  "notes": "Complete overhaul of company website",
  "area": "Work",
  "deadline": "2024-03-15",
  "tags": ["urgent", "web-dev"]
}

Create a Todo

Creates a new to-do in Things3.

• Required: title (string)
• Optional:
  • notes (string)
  • when (string) - Date/time to start
  • deadline (string) - Due date
  • checklist (array of strings)
  • tags (array of strings)
  • list (string) - Project or area to assign to
  • heading (string) - Group under this heading

Example:

{
  "title": "Review design mockups",
  "notes": "Check the new homepage designs",
  "list": "Website Redesign", 
  "deadline": "2024-02-20",
  "tags": ["review"],
  "checklist": ["Check mobile responsiveness", "Verify brand guidelines", "Test accessibility"]
}

Management Operations

Complete a Todo

Mark a todo as completed by searching for its title.

• Required: title (string) - Title or partial title to search for
• Returns: Success/failure message

Example:

{
  "title": "Review design"
}

Search Todos

Search for todos by title or content.

• Required: query (string) - Search term
• Returns: List of matching todos with status and metadata

Example:

{
  "query": "website"
}

Natural Language Integration

This MCP server works seamlessly with Claude AI. Once configured, you can use natural language to manage your Things3 tasks:

• "Create a project called 'Q1 Planning' with a deadline of March 31st"
• "Add a todo to review the budget with a checklist of tasks"
• "Show me all my tasks for today"
• "Mark the 'Call client' task as completed"
• "Search for all todos related to the website project"

Troubleshooting

Common Issues

"Things3 is not available"

• Ensure Things3 is installed and running
• Grant AppleScript permissions when prompted
• Check Things3 is not in a permission-restricted mode

"Failed to execute AppleScript"

• Verify macOS security settings allow AppleScript
• Ensure Things3 has necessary accessibility permissions
• Try restarting Things3

URL encoding issues with special characters

• The server handles unicode and special characters
• If issues persist, check the logs for specific URL construction errors

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "things3" '{"command":"mcp-server-things3","args":[]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect