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

📋 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:

1. System Preferences → Security & Privacy → Privacy → Accessibility

2. Click the lock to make changes (enter your password)

3. Add your MCP client (e.g., Claude Desktop, Cursor, Terminal)

4. Enable the checkbox for the application

2. AppleScript Permissions

The server may also need AppleScript permissions:

1. System Preferences → Security & Privacy → Privacy → Automation

2. Find your MCP client in the list

3. Enable "Things3" under your client application

3. Terminal/Ruby Permissions (if running directly)

If running the server directly from Terminal:

1. System Preferences → Security & Privacy → Privacy → Accessibility

2. Add Terminal (or your terminal app)

3. Enable the checkbox

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

🛠 Installation

1. Clone the repository:

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

2. Install dependencies:

bundle install

3. Run the MCP server:

./things3-mcp-server

4. Configure in your MCP client - See MCP Client Configuration below

🔌 MCP Client Configuration

Claude Desktop

1. Find your config file:

2. Add the server configuration:

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

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

Cursor IDE

1. Open Cursor Settings (`Cmd + ,`)

2. Navigate to Extensions → MCP

3. Add server configuration:

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

VS Code (with MCP Extension)

1. Install an MCP extension from the VS Code marketplace

2. Open VS Code Settings (`Cmd + ,`)

3. Search for "MCP" and add server:

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

Zed Editor

1. Open Zed settings (`Cmd + ,`)

2. Add to your `settings.json`:

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

Continue (VS Code Extension)

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

2. 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

1. Use absolute paths - Relative paths may not work across different clients

2. Check permissions - Ensure the executable has proper permissions (`chmod +x`)

3. Test the server - Run `./things3-mcp-server` manually to verify it works

4. 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.

🎯 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

🔧 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}
})

🛡️ 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

🔍 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.

🤝 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.