MCP Server for Things3

A robust MCP (Model Context Protocol) server providing comprehensive integration with Things3, allowing you to create, manage, and search tasks and projects through the MCP protocol. Features improved error handling, secure URL encoding, and enhanced AppleScript integration.

Features

• ✅ Create Projects: Create new projects in Things3 with full metadata support
• ✅ Create Todos: Create new to-dos with detailed properties including checklists, tags, and dates
• ✅ View Tasks: List tasks from inbox, today's list, or all projects
• ✅ Complete Tasks: Mark todos as completed by searching for their title
• ✅ Search Functionality: Search through all todos by title or content
• ✅ Robust Error Handling: Comprehensive validation and error recovery
• ✅ Secure URL Encoding: Proper handling of special characters and unicode
• ✅ AppleScript Integration: Safe, non-JSON string concatenation approach

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

Tools Available

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-things3-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-things3-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-things3-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-things3-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"
}

Integration with Claude

This MCP server is designed to work 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"

Con

... View full README on GitHub