Things3 Mcp Tools

Except for specific skills and scripts that I added, I would recommend this MCP instead: https://github.com/hald/things-mcp

---

Model Context Protocol (MCP) tools for Things3 task management with optional Notion integration. Provides comprehensive automation for Things3 via AppleScript and direct SQLite access, with Claude Code skills for workflow guidance.

Demo

https://github.com/user-attachments/assets/42e9f9a0-28b8-40d1-98d6-5d6c7457f23f

What This Provides

MCP Tools for Things3:

• Complete task management (create, read, update, delete, search)
• Direct SQLite access for fast search across titles and notes
• AppleScript integration for reliable task manipulation
• Bulk operations (tagging, moving, completing tasks)
• Project and area management

Optional Notion Integration:

• Migrate Things3 inbox items to Notion
• Cross-system workflow patterns via Claude skills

Claude Code Skills:

• Auto-loading workflow guidance for productivity tasks
• Personal taxonomy integration for work contexts
• Best practices and automation patterns

Repository Structure

.
├── .claude/skills/          # Claude Code auto-loading skills
│   ├── things3-productivity/    # Things3 workflows and patterns
│   ├── notion-workflows/        # Notion organization patterns
│   └── productivity-integration/ # Cross-system workflows
├── tooling/                 # MCP server and tools
│   ├── mcp-server/             # MCP server configuration
│   └── scripts/                # Tool implementations
└── private-prefs.example.json  # Template for personal preferences

Setup

Prerequisites

• macOS with Things3 installed
• Python 3.11+
• Claude Code (for skills integration)
• Optional: Notion account (for Notion integration features)

Installation

1. Install dependencies:

   cd tooling
   pip install -r requirements.txt
   

2. Configure MCP server in Claude Code: Add to your Claude Code MCP settings:

   {
     "mcpServers": {
       "things3-notion": {
         "command": "node",
         "args": ["/path/to/tooling/mcp-server/build/index.js"],
         "env": {
           "SCRIPTS_DIR": "/path/to/tooling/scripts"
         }
       }
     }
   }
   

3. Optional: Set up personal preferences:

   cp private-prefs.example.json private-prefs/personal-taxonomy.json
   # Edit with your tags, areas, and preferences
   

Adding Notion MCP (Optional)

You can use both Things3 and Notion MCP tools together in Claude Code. You can read about the Notion MCP here.

Available Tools

Task Management

• read_tasks - List and filter tasks by list, area, project, tags, priority, or status
• search_tasks - Fast SQLite search across task titles and notes
• create_task - Create new tasks with tags, scheduling, and project assignment
• edit_task - Modify existing tasks (title, notes, tags, scheduling, completion)
• delete_tasks - Move tasks to trash (with confirmation)
• complete_tasks - Mark tasks as completed
• move_tasks - Move tasks between lists (Today, Anytime, Someday, etc.)

Organization

• add_tags / remove_tags - Bulk tag management
• list_areas / list_projects / list_tags - Browse organizational structure
• create_project / create_area - Create new organizational containers
• get_project_tasks - View all tasks within a project
• get_selected - Get currently selected tasks from Things3 UI

Integration

• migrate_inbox_to_notion - Transfer Things3 inbox items to Notion blocks

Usage Examples

Search for tasks

# Find task by partial title
search_tasks(query="meeting", when="today")

# Search with filters
search_tasks(query="bug", area="Work", tags=["urgent"])

Read tasks from a list

# Get today's tasks
read_tasks(when="today")

# Filter by area and priority
read_tasks(when="today", area="Work", min_priority=7)

# List projects in an area
read_tasks(area="Work", list_projects=True)

Create and manage tasks

# Create a task
create_task(
    title="Review PR",
    notes="Check for test coverage",
    when="today",
    tags=["code-review"],
    area="Work"
)

# Edit a task
edit_task(
    task_uuid="abc-123",
    tags=["urgent", "code-review"],
    when="today"
)

# Bulk operations
complete_tasks(task_uuids=["abc-123", "def-456"])
add_tags(task_uuids=["abc-123"], tags=["waiting"])

Personal Preferences (Optional but Recommended)

The tools support personal taxonomy for automatic context injection. Create private-prefs/personal-taxonomy.json based on the example template to define:

• Work tags: Your work identification tag (e.g., "WORK", "CLIENT") - tools automatically recognize tasks with this tag as work-related
• Work areas: Your professional focus areas
• Priority system: Your 1-9 priority preferences
• Common project patterns: Typical project structures
• Notion integration mappings: Block IDs for migration

Important: Tools like read_tasks and search_tasks use the work_tag from your personal preferences to identify work tasks. Without preferences, they default to looking for a "WORK" tag.

Example private-prefs/personal-taxonomy.json:

{
  "things3": {
    "work_classification": {
      "work_tag": "YOUR_WORK_TAG",
      "work_areas": ["Your Work Area"]
    }
  }
}

Personal preferences are automatically loaded by tools when available, but all tools work without them using sensible defaults.

Claude Code Skills

Skills in .claude/skills/ provide auto-loading workflow guidance:

• things3-productivity - Task management patterns, query strategies, automation workflows
• notion-workflows - Workspace organization, content reuse patterns
• productivity-integration - Cross-system automation strategies
• inbox-processing.example - Example workflow for batch inbox processing (see directory for customization guide)

Skills reference personal preferences automatically to provide contextual guidance.

Note: You may have private skills in .claude/skills/ that are gitignored (e.g., inbox-processing/ with personal workflow patterns). These won't appear in the repository but will be available locally for your use.

Development

Running Tools Directly

Tools can be executed from command line for testing:

cd tooling/scripts
python3 read_tasks.py --when today --json
python3 search_tasks.py "meeting" --when today
python3 create_task.py --title "Test task" --when today

Adding New Tools

1. Create script in tooling/scripts/
2. Add tool definition to tooling/mcp-server/tools-manifest.json
3. Restart Claude Code MCP server

Architecture

• AppleScript layer: Reliable task manipulation via Things3's native API
• things.py: Direct SQLite access for fast search operations
• MCP server: Standard interface for Claude Code integration
• Skills: Auto-loading workflow guidance and personal context