Things 3

from mattsafaii

Manage your tasks and projects in Things 3 on macOS.

🔥🔥🔥✓ VerifiedFreeAdvanced setup

#automation #calendar #analytics #git #security #monitoring

Things 3 MCP Server (Ruby)

A comprehensive Model Context Protocol (MCP) server for Things 3 task management on macOS. This server provides natural language task management, advanced filtering, bulk operations, analytics, and maintenance tools through AppleScript integration.

macOS Only: This MCP server requires macOS and Things 3 (which is macOS-exclusive).

🏗️ Architecture

The codebase is organized into focused classes with clear separation of concerns:

Things3MCPServer - Main MCP server implementation
AppleScriptExecutor - Handles AppleScript execution with error handling
AppleScriptGenerator - Generates AppleScript code for Things 3 operations
Things3Client - Core Things 3 task operations (CRUD)
DateParser - Natural language date parsing using Chronic gem
TaskFilter - Advanced task filtering and search capabilities
BulkOperations - Bulk task operations (create, update, move, complete, import)
ReportGenerator - Weekly reviews, project reports, and analytics

🚀 Features

Core Task Management

CRUD Operations: Create, read, update, delete tasks
Natural Language Dates: "tomorrow", "next Friday", "in 3 days", etc.
Smart Organization: Project/area assignment with automatic creation
Advanced Search: Multi-criteria filtering with regex support

Advanced Filtering

Complex Filters: Status, projects, areas, tags, dates, notes
Quick Filters: Pre-built filters for common scenarios
Saved Filters: Store and reuse complex filter combinations
Text Search: Name and notes content search with regex

Bulk Operations

Mass Creation: Create multiple tasks from lists or templates
Bulk Updates: Update tasks matching specific criteria
Tag Operations: Add, remove, standardize tags across tasks
Import/Export: CSV, JSON, and plain text import support

Analytics & Reports

Weekly Reviews: Comprehensive review generation
Project Health: Analyze project progress and bottlenecks
Productivity Insights: Completion patterns and trends
Planning Tools: Next week planning with energy-based scheduling

Data Maintenance

Duplicate Detection: Find and merge similar tasks
Orphaned Task Cleanup: Organize tasks without projects/areas
Tag Standardization: Clean up inconsistent tag naming
System Health: Organization scoring and health metrics

🎯 Available Tools

33 comprehensive tools organized into functional categories:

Core Task Operations

add_task - Create new tasks with full metadata
list_tasks - List tasks with filtering options
list_projects - List all projects and areas
update_task - Modify existing task properties
complete_task - Mark tasks as completed
delete_task - Remove tasks from Things 3
move_task - Move tasks between projects/areas
search_tasks - Search task names and content

Advanced Features

add_task_with_planning_notes - Create tasks with planning metadata
list_tasks_by_date_range - Filter tasks by date ranges
snooze_task - Postpone tasks to future dates
parse_date - Test natural language date parsing

Filtering & Search

filter_tasks - Advanced multi-criteria filtering
quick_filters - Pre-built useful filters (orphaned, overdue, etc.)
saved_filters - Manage reusable filter configurations

Analytics & Reports

weekly_review - Generate comprehensive weekly reviews
project_status_report - Analyze active projects
productivity_insights - Track productivity patterns
next_week_planning - Plan upcoming week with energy levels
review_templates - Manage consistent review formats

Bulk Operations

bulk_create_tasks - Create multiple tasks at once
bulk_update_tasks - Update multiple matching tasks
bulk_move_tasks - Move tasks between projects
bulk_tag_operations - Mass tag management
bulk_complete_tasks - Complete multiple tasks
bulk_import_tasks - Import from external formats

Data Cleanup & Maintenance

cleanup_orphaned_tasks - Organize unassigned tasks
find_duplicate_tasks - Detect and merge duplicates
standardize_tags - Clean up tag naming consistency
cleanup_stale_tasks - Handle old/abandoned tasks
analyze_project_health - Project health metrics
fix_broken_references - Repair data integrity issues
organization_score - Overall system health assessment

Templates & Automation

task_templates - Manage reusable task sets

🛡️ Error Handling

Things 3 Availability: Validates Things 3 is running before operations
AppleScript Errors: Comprehensive error catching with descriptive messages
Date Parsing: Graceful handling of ambiguous dates with confidence indicators
Input Validation: Parameter validation with helpful error messages
Timeout Protection: 30-second timeout on AppleScript operations

📁 File Structure

things3-mcp/
├── things3-mcp-server            # Executable script (root level)
├── lib/
│   ├── things3_mcp.rb            # Main entry point
│   └── things3_mcp/
│       ├── server.rb             # MCP server implementation
│       ├── client.rb             # Core Things 3 operations
│       ├── date_parser.rb        # Natural language date parsing
│       ├── task_filter.rb        # Advanced task filtering
│       ├── bulk_operations.rb    # Bulk task operations
│       ├── report_generator.rb   # Analytics and reports
│       └── applescript/
│           ├── executor.rb       # AppleScript execution engine
│           └── generator.rb      # AppleScript code generation
├── Gemfile                       # Ruby dependencies
├── Gemfile.lock                  # Locked dependency versions

└── README.md                     # This documentation

🤝 MCP Integration

This server implements the Model Context Protocol and can be used with any MCP-compatible client:

Claude Desktop - Most popular MCP client
Cursor IDE - AI-powered code editor with MCP support
VS Code - With MCP extensions
Zed Editor - Modern editor with built-in MCP support
Continue - VS Code extension for AI coding assistance
Custom Applications - Any tool implementing the MCP standard

See the MCP Client Configuration section above for detailed setup instructions for each client.

The server provides a natural language interface to comprehensive Things 3 task management through the standardized MCP protocol, making your task management available to any AI assistant or automation tool that supports MCP.

📄 Dependencies

mcp (~> 0.1.0) - Model Context Protocol implementation
chronic (~> 0.10.2) - Natural language date parsing
debug, rubocop (development)

📊 System Health

The server includes built-in health monitoring through:

Organization scoring (0-100 across multiple dimensions)
Project health analysis
Duplicate detection
Data integrity checks
Productivity trend analysis

Regular maintenance can be automated through the provided cleanup and analysis tools.

📋 Requirements

macOS: Required (Things 3 is macOS-only)
Things 3: Must be installed and running
Ruby: Version 3.0.0 or higher
Dependencies: Managed via Bundler

Note: This MCP server only works on macOS since Things 3 is an exclusive macOS application.

🔐 macOS Permissions Setup

This MCP server uses AppleScript to communicate with Things 3, which requires specific macOS permissions:

1. Accessibility Permissions

When you first run the MCP server, macOS will prompt for accessibility permissions:

System Preferences → Security & Privacy → Privacy → Accessibility
Click the lock to make changes (enter your password)
Add your MCP client (e.g., Claude Desktop, Cursor, Terminal)
Enable the checkbox for the application

2. AppleScript Permissions

The server may also need AppleScript permissions:

System Preferences → Security & Privacy → Privacy → Automation
Find your MCP client in the list
Enable "Things3" under your client application

3. Terminal/Ruby Permissions (if running directly)

If running the server directly from Terminal:

System Preferences → Security & Privacy → Privacy → Accessibility
Add Terminal (or your terminal app)
Enable the checkbox

💡 Tip: If you get "permission denied" errors, restart your MCP client after granting permissions.

🛠 Installation

Clone the repository:

git clone https://github.com/mattsafaii/things3-mcp.git
cd things3-mcp

Install dependencies:
```
bundle install
```
Run the MCP server:
```
./things3-mcp-server
```
Configure in your MCP client - See MCP Client Configuration below

🔌 MCP Client Configuration

Claude Desktop

Find your config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the server configuration:

{
  "mcpServers": {
    "things3": {
      "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
      "args": []
    }
  }
}

Restart Claude Desktop - The server will appear in your available tools

Cursor IDE

Open Cursor Settings (Cmd + ,)
Navigate to Extensions → MCP

Add server configuration:

{
  "name": "Things3",
  "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
  "args": []
}

VS Code (with MCP Extension)

Install an MCP extension from the VS Code marketplace
Open VS Code Settings (Cmd + ,)

Search for "MCP" and add server:

{
  "mcp.servers": [
    {
      "name": "things3",
      "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
      "args": []
    }
  ]
}

Zed Editor

Open Zed settings (Cmd + ,)

Add to your settings.json:

{
  "language_models": {
    "mcp_servers": {
      "things3": {
        "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
        "args": []
      }
    }
  }
}

Continue (VS Code Extension)

Open Continue configuration (.continue/config.json in your workspace)

Add MCP server:

{
  "mcpServers": {
    "things3": {
      "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
      "args": []
    }
  }
}

Generic MCP Client

For any MCP client that supports the standard, use:

{
  "name": "things3",
  "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
  "args": [],
  "env": {
    "PATH": "/usr/local/bin:/usr/bin:/bin"
  }
}

Configuration Tips

Use absolute paths - Relative paths may not work across different clients
Check permissions - Ensure the executable has proper permissions (chmod +x)
Test the server - Run ./things3-mcp-server manually to verify it works
Check logs - Most MCP clients provide logs for debugging connection issues

Verifying Installation

Once configured, you should see these tools available in your MCP client:

add_task, list_tasks, complete_task (core operations)
weekly_review, project_status_report (analytics)
bulk_create_tasks, filter_tasks (advanced features)
And 30+ other specialized tools

Test with a simple command:

"Add a task called 'Test MCP integration' to my Things 3"

If successful, you'll see the task appear in Things 3 and get a confirmation message.

First Run: On first use, macOS will prompt for permissions (see macOS Permissions Setup). Grant the permissions and restart your MCP client.

🔧 Configuration

Saved Filters Storage

Filters are automatically saved to: ~/.things3_mcp_filters.json

Debug Mode

Enable detailed logging by setting debug flags in the class constructors or through environment variables.

📖 Usage Examples

Basic Task Management

# Add simple task
add_task({"name": "Buy groceries"})

# Add task with project and due date
add_task({
  "name": "Finish quarterly report", 
  "project": "Work",
  "due_date": "next Friday",
  "tags": ["urgent", "quarterly"]
})

Natural Language Dates

# Various supported formats
add_task({"name": "Team meeting", "due_date": "tomorrow at 2pm"})
add_task({"name": "Vacation planning", "due_date": "end of month"})
add_task({"name": "Project review", "start_date": "next Monday", "due_date": "in 2 weeks"})

Advanced Filtering

# Complex filter
filter_tasks({
  "status": ["open"],
  "project_names": ["Work", "Personal"],
  "tag_filter": {"has_tags": ["urgent"]},
  "date_filter": {"overdue": true}
})

# Quick filters
quick_filters({"filter_type": "orphaned_tasks"})

Weekly Review Workflow

# Generate comprehensive review
weekly_review({
  "review_type": "last_week",
  "include_sections": ["completed", "overdue", "upcoming", "projects", "insights"]
})

# Project health check
project_status_report({"include_metrics": true})

# Plan next week
next_week_planning({"include_energy_levels": true})

Bulk Operations

# Create multiple tasks
bulk_create_tasks({
  "tasks": [
    {"name": "Research competitors", "project": "Website"},
    {"name": "Design mockups", "project": "Website", "due_date": "Friday"},
    {"name": "Write content", "project": "Website"}
  ]
})

# Standardize tags
standardize_tags({
  "apply": true,
  "rules": {"lowercase": true, "merge_similar": true}
})

🔍 Troubleshooting

Common Issues

Things 3 Not Running

Error: Things 3 is not available

Solution: Launch Things 3 application

AppleScript Permission Denied

Error: AppleScript execution failed - permission denied

Solutions:

Grant Accessibility permissions: System Preferences → Security & Privacy → Privacy → Accessibility
Grant Automation permissions: System Preferences → Security & Privacy → Privacy → Automation
Add your MCP client (Claude Desktop, Cursor, etc.) to both permission lists
Restart your MCP client after granting permissions
If running directly, add Terminal to Accessibility permissions

Date Parsing Issues

Error: Could not parse date: 'next Flursday'

Solution: Use supported formats like "next Friday", "in 3 days", or "YYYY-MM-DD"

AppleScript Timeout

Error: AppleScript execution timeout

Solution: Reduce bulk operation size or check Things 3 performance

MCP Server Not Connecting

Error: MCP server failed to start

Solutions:

Verify the absolute path to things3-mcp-server is correct
Check that the executable has proper permissions (chmod +x things3-mcp-server)
Test the server manually: ./things3-mcp-server
Check MCP client logs for detailed error messages
Ensure Ruby and dependencies are properly installed

MCP Tools Not Appearing

No Things3 tools available in client

Solutions:

Restart your MCP client after configuration changes
Verify the JSON configuration syntax is valid
Check that the server name doesn't conflict with other MCP servers
Look for connection errors in client logs

Debug Mode

Enable detailed logging by setting debug: true in class constructors for troubleshooting.