acekapila/things3-mcp-server

Things 3 MCP Server

A Model Context Protocol (MCP) server that provides integration with Things 3 and Calendar app on macOS. This server allows AI assistants and other MCP clients to interact with your Things 3 tasks, projects, and areas through a standardized interface.

Features

To-Do Management

• Add To-Dos: Create new tasks with title, notes, due date, tags, and assign to specific lists, projects, or areas
• List To-Dos: Retrieve tasks from any list (Inbox, Today, Anytime, Upcoming, Someday, Logbook, Trash) or from specific projects/areas
• Update To-Dos: Modify existing tasks (title, notes, due date, tags)
• Complete To-Dos: Mark tasks as completed
• Delete To-Dos: Move tasks to trash

Project Management

• Add Projects: Create new projects with notes, tags, and area assignment
• List Projects: View all projects filtered by status (open, completed, all) or area

Area Management

• Add Areas: Create new areas of responsibility
• List Areas: View all areas

Additional Features

• Search: Search across all to-dos, projects, and areas
• Daily Overview: Get a summary of today's tasks and counts
• Quick Entry: Open Things 3's Quick Entry panel with optional pre-filled content

Requirements

• macOS (Things 3 is Mac-only)
• Things 3 installed
• Python 3.7+
• MCP package

Installation

1. Clone this repository or download the server files
2. Install dependencies:

   pip install -r requirements.txt
   

3. (Optional) Install as a package:

   pip install -e .
   

Configuration

For Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "things3": {
      "command": "python3",
      "args": ["/path/to/things3_server.py"],
      "env": {}
    },
   "calendar": {
      "command": "python3", 
      "args": ["/path/to/calendar_server.py"]
    }
  }
}

For Other MCP Clients

Use the provided mcp.json configuration file or run directly:

python things3_server.py

The server communicates via stdin/stdout, making it compatible with any MCP client.

Available Tools

1. things3_add_todo

   • Add a new to-do with optional properties
   • Parameters: title (required), notes, due_date, tags, list, project, area

2. things3_list_todos

   • List to-dos from a specific list, project, or area
   • Parameters: list, project, area, limit

3. things3_complete_todo

   • Mark a to-do as completed
   • Parameters: title (required)

4. things3_update_todo

   • Update an existing to-do
   • Parameters: title (required), new_title, notes, due_date, tags

5. things3_delete_todo

   • Move a to-do to trash
   • Parameters: title (required)

6. things3_add_project

   • Create a new project
   • Parameters: title (required), notes, area, tags, when

7. things3_list_projects

   • List projects with filters
   • Parameters: status, area

8. things3_add_area

   • Create a new area
   • Parameters: title (required), tags

9. things3_list_areas

   • List all areas
   • No parameters

10. things3_search

    • Search across all items
    • Parameters: query (required), limit

11. things3_daily_overview

    • Get today's task summary
    • No parameters

12. things3_quick_entry

    • Open Quick Entry panel
    • Parameters: title, notes, autofill