Things 3

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

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

- 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

- 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

- 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

- 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

- 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

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

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

When you first run the MCP server, macOS will prompt for accessibility permissions:
- System Preferences→Security & Privacy→Privacy→Accessibility
- Click the lockto make changes (enter your password)
- Add your MCP client(e.g., Claude Desktop, Cursor, Terminal)
- Enable the checkboxfor the application

The server may also need AppleScript permissions:
- System Preferences→Security & Privacy→Privacy→Automation
- Find your MCP clientin 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.

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

Configure in your MCP client- SeeMCP Client Configurationbelow

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

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

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

-

Install an MCP extensionfrom the VS Code marketplace

Search for "MCP" and add server:

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

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

-

Open Continue configuration(.continue/config.jsonin your workspace)

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

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

- 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-servermanually to verify it works
- Check logs- Most MCP clients provide logs for debugging connection issues

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

"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 (seemacOS Permissions Setup). Grant the permissions and restart your MCP client.

# 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"] })

# 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"})

# 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"})

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

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

- 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

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

Error: AppleScript execution failed - permission denied

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

Error: Could not parse date: 'next Flursday'

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

Solution: Reduce bulk operation size or check Things 3 performance

- Verify the absolute path tothings3-mcp-serveris 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

- 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

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

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 theMCP Client Configurationsection above for detailed setup instructions for each client.

Enables LLM clients to interact with macOS applications through AppleScript. Built using the @beyondbetter/bb-mcp-server library, this server provides safe, controlled execution of predefined scripts with optional support for arbitrary script execution.