Things 3 MCP Server

This Model Context Protocol (MCP) server lets you use Claude Desktop to interact with your task management data in Things 3. You can ask Claude or your MCP client of choice to create tasks, analyze projects, help manage priorities, and more.

This MCP server leverages a combination of the Things.py library and Things 3’s AppleScript support, enabling reading and writing to Things 3.

Why Things MCP?

This MCP server unlocks the power of AI for your task management:

• Natural Language Task Creation: Ask Claude to create richly-detailed tasks and descriptions in natural language
• Smart Task Analysis: Let Claude explore your project lists and focus areas and provide insights into your work
• GTD & Productivity Workflows: Let Claude help you implement productivity and prioritisation systems
• Seamless Integration: Works directly with your existing Things 3 data

Features

• Access to all major Things lists (Inbox, Today, Upcoming, Logbook, Someday, etc.)
• Project and Area management and assignment
• Tagging operations for tasks and projects
• Advanced search capabilities
• Recent items tracking
• Support for nested data (projects within areas, todos within projects)
• Checklist/Subtask support - Read and display existing checklist items from todos

Installation

Prerequisites

• Python 3.12+
• Claude Desktop
• Things 3 for MacOS

Step 1: Install the package

Option A: Install from PyPI in a virtual environment (recommended)

# Create a virtual environment in your home directory
python3 -m venv ~/.venvs/things3-mcp-env
source ~/.venvs/things3-mcp-env/bin/activate

# Install the package
pip install Things3-MCP-server==2.0.6

Option B: Install from source (for development/contributors)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Restart your terminal afterwards

# Clone and install the package with development dependencies
git clone https://github.com/rossshannon/Things3-MCP
cd Things3-MCP
uv venv
uv pip install -e ".[dev]"  # Install in development mode with extra dependencies

Step 2: Configure Claude Desktop

Edit the Claude Desktop configuration file:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add the Things server to the mcpServers key in the configuration file:

Option A: Using PyPI package in virtual environment

{
    "mcpServers": {
        "things": {
            "command": "~/.venvs/things3-mcp-env/bin/Things3-MCP-server"
        }
    }
}

Option B: Using source installation (for development/contributors)

{
    "mcpServers": {
        "things": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/Things3-MCP",
                "run",
                "Things3-MCP-server"
            ]
        }
    }
}

Step 3: Restart Claude Desktop

Restart the Claude Desktop app to enable the integration.

Sample Usage with Claude Desktop

• “What’s on my todo list today?”
• “Create a todo to prepare for each of my 1-on-1s next week”
• “Evaluate my todos scheduled for today using the Eisenhower matrix.”
• “Help me conduct a GTD-style weekly review using Things.”

Tips

• Create a Project in Claude with custom instructions that explains how you use Things and organize areas, projects, tags, etc. Tell Claude what information you want included when it creates a new task (e.g., asking it to include relevant details in the task description, whether to use emojis, etc.).
• Try combining this with another MCP server that gives Claude access to your calendar. This will let you ask Claude to block time on your calendar for specific tasks, create tasks that relate to upcoming calendar events (e.g., prep for a meeting), etc.

Available Tools

List Views

• get_inbox - Get todos from Inbox
• get_today - Get todos due today
• get_upcoming - Get upcoming todos
• get_anytime - Get todos from Anytime list
• get_someday - Get todos from Someday list
• get_logbook - Get completed todos
• get_trash - Get trashed todos

Random Sampling (for LLM Enrichment)

• get_random_inbox - Get a random sample of todos from Inbox
• get_random_anytime - Get a random sample of items from Anytime list
• get_random_todos - Get a random sample of todos, optionally filtered by project

Basic Operations

• get_todos - Get todos, optionally filtered by project
• get_projects - Get all projects
• get_areas - Get all areas

Tag Operations

• get_tags - Get all tags
• get_tagged_items - Get items with a specific tag

Search Operations

• search_todos - Simple search by title/notes
• search_advanced - Advanced search with multiple filters

Time-based Operations

• get_recent - Get recently created items

Modification Operations

• add_todo - Create a new todo with full parameter support
• add_project - Create a new project with tags and todos
• update_todo - Update an existing todo
• update_project - Update an existing project
• show_item - Show a specific item or list in Things
• search_items - Search for items in Things

Tool Parameters

get_todos

• project_uuid (optional) - Filter todos by project

get_projects / get_areas / get_tags

• include_items (optional, default: false) - Include contained items

search_advanced

• status - Filter by status (incomplete/completed/canceled)
• start_date - Filter by start date (YYYY-MM-DD)
• deadline - Filter by deadline (YYYY-MM-DD)
• tag - Filter by tag
• area - Filter by area UUID
• type - Filter by item type (to-do/project/heading)

get_recent

• period - Time period (e.g., '3d', '1w', '2m', '1y')
• limit - Maximum number of items to return

Random Sampling Tools

• get_random_inbox(count=5) - Get random sample from Inbox
• get_random_anytime(count=5) - Get random sample from Anytime list
• get_random_todos(project_uuid=None, count=5) - Get random sample of todos, optionally from specific project

add_todo

• title - Title of the todo
• notes (optional) - Notes for the todo (supports Markdown formatting including checkboxes like - [ ] Task)
• when (optional) - When to schedule the todo (today, tomorrow, evening, anytime, someday, or YYYY-MM-DD)
• deadline (optional) - Deadline for the todo (YYYY-MM-DD)
• tags (optional) - Tags to apply to the todo
• list_title (optional) - Title of project/area to add to (must exactly match existing name)
• list_id (optional) - ID of project/area to add to (takes priority over list_title if both provided)
• Note: While Things’ native checklist feature (i.e., subtasks) cannot be created via AppleScript, you and your LLMs can use Markdown checkboxes in the notes field to achieve similar functionality.

update_todo

• id - ID of the todo to update
• title (optional) - New title
• notes (optional) - New notes
• when (optional) - When to schedule the todo (today, tomorrow, evening, anytime, someday, or YYYY-MM-DD)
• deadline (optional) - Deadline for the todo (YYYY-MM-DD)
• tags (optional) - New tags
• completed (optional) - Mark as completed
• canceled (optional) - Mark as canceled
• list_name (optional) - Name of built-in list, project, or area to move the todo to. For built-in lists use: "Inbox", "Today", "Anytime", "Someday". For projects/areas, use the exact name.
• list_id (optional) - ID of project/area to move the todo to (takes priority over list_name if both provided)

add_project

• title - Title of the project
• notes (optional) - Notes for the project
• when (optional) - When to schedule the project
• deadline (optional) - Deadline for the project
• tags (optional) - Tags to apply to the project
• area_title or area_id (optional) - Title or ID of area to add to (must exactly match an existing area title — look them up with get_areas)
• todos (optional) - Initial todos to create in the project

update_project

• id - ID of the project to update
• title (optional) - New title
• notes (optional) - New notes
• when (optional) - When to schedule the project (today, tomorrow, evening, anytime, someday, or YYYY-MM-DD)
• deadline (optional) - Deadline for the project (YYYY-MM-DD)
• tags (optional) - New tags
• completed (optional) - Mark as completed
• canceled (optional) - Mark as canceled

show_item

• id - ID of item to show, or one of: inbox, today, upcoming, anytime, someday, logbook
• query (optional) - Optional query to filter by
• filter_tags (optional) - Optional tags to filter by

Usage Examples

Creating Todos with List Assignment

# Create todo in Inbox (default)
add_todo(title="Review quarterly report")

# Create todo in a built-in list
add_todo(title="Call dentist", when="today")
add_todo(title="Plan vacation", when="someday")

# Create todo in a project by name
add_todo(title="Design new logo", list_title="Website Redesign")

# Create todo in a project by ID (more precise, recommended for automation)
add_todo(title="Write documentation", list_id="ABC123DEF456")

# When both are provided, list_id takes priority
add_todo(
    title="Important task",
    list_id="ABC123DEF456",     # This will be used
    list_title="Other Project"  # This will be ignored
)

Moving Todos Between Lists

# Move to built-in list
update_todo(id="TODO123", list_name="Today")
update_todo(id="TODO456", list_name="Someday")

# Move to project by name
update_todo(id="TODO789", list_name="Website Redesign")

# Move to project by ID (recommended for precision)
update_todo(id="TODO101", list_id="ABC123DEF456")

When to Use ID vs Title

• Use list_title/list_name when:

  • Working interactively with human-readable names
  • You're certain the name is unique and won't change
  • Creating simple scripts or one-off tasks

• Use list_id when:

  • Building automation or applications
  • You need precision and reliability
  • Working with projects/areas that might have similar names

Using Tags

Things will automatically create missing tags when they are added to a task or project. Configure your LLM to do a lookup of your tags first before making changes if you want to control this.

LLM Enrichment Workflows

The random sampling tools (get_random_inbox, get_random_anytime, get_random_todos) are designed for iterative task improvement workflows where you want to gradually enhance your todo items using AI assistance.

Use Cases

Incremental Task Enhancement

• Pull 5 random todos from your Inbox to add better descriptions, break down into subtasks, or estimate time requirements
• Sample from your Anytime list to identify tasks that could benefit from better scheduling or prioritization
• Avoid downloading hundreds of tasks into context when you only need a few

Content Enrichment

• Add or improve context and suggest more actionable language
• Add context, dependencies, or next steps to existing todos
• Standardize formatting across your task descriptions
• Find tasks that might be too vague or overly complex
• Discover todos that could be automated or delegated

Development

This project uses pyproject.toml to manage dependencies and build configuration. It's built using the Model Context Protocol, which allows Claude to securely access tools and data.

Development Workflow

Setting up a development environment

# Clone the repository
git clone https://github.com/rossshannon/Things3-MCP
cd Things3-MCP

# Set up a virtual environment with development dependencies
uv venv
uv pip install -e ".[dev]"  # Install in development mode with extra dependencies

Testing changes during development

Run the comprehensive test suite to ensure everything is working as expected:

# Run all tests (116 tests, ~3-4 minutes)
uv run pytest

# Run tests with coverage report
uv run pytest --cov=things3_mcp --cov-report=term-missing

# Run specific test file
uv run pytest tests/test_list_assignment_operations.py

# Run tests with minimal output
uv run pytest -q

# Run tests matching a pattern
uv run pytest -k "error_handling"

Test Configuration:

• 116 comprehensive tests covering all functionality
• Automatic cleanup - tests don't affect your existing Things data
• Edge case coverage - malformed UUIDs, timeouts, error conditions
• Integration testing - tests against real Things app

The tests clean up after themselves and don't affect your existing data, so you can run them as often as you like.

Troubleshooting

The server includes error handling for:

• Invalid UUIDs
• Missing required parameters
• Things database access errors
• Data formatting errors
• Authentication token issues
• AppleScript execution failures

Common Issues

1. Things app not running: Make sure the Things app is running on your Mac for AppleScript methods to work.

Checking Logs

All errors are logged and returned with descriptive messages. To review the MCP logs:

# Follow main logs in real-time
tail -f ~/.things-mcp/logs/things3_mcp.log

# Check error logs
tail -f ~/.things-mcp/logs/things3_mcp_errors.log

# View structured logs for analysis
cat ~/.things-mcp/logs/things3_mcp_structured.json | jq

# Claude Desktop MCP logs
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Acknowledgements

This MCP server was originally based on the Applescript bridge method from things-mcp by excelsier, which was in turn based on things-mcp by hald.