Things 3 Extended MCP Server - DXT Extension

A comprehensive Desktop Extension (DXT) for Things 3 task management integration with enhanced capabilities including task movement, editing, and backup functionality.

Features

📋 Viewing Operations

view_inbox - View all tasks in Things 3 inbox
view_today - View all tasks scheduled for today
view_projects - View all projects in Things 3
view_areas - View all areas in Things 3

➕ Creation Operations

create_task - Create new tasks with full metadata (notes, dates, tags, checklists)
create_project - Create new projects with areas and scheduling
create_area - Create new organizational areas

🔄 Task Movement Operations

move_task_to_inbox - Move tasks from today/other lists back to inbox
move_task_to_today - Schedule inbox tasks for today
move_task_to_project - Assign tasks to specific projects
move_task_to_area - Move tasks to specific areas

✏️ Editing Operations

edit_task - Modify existing task properties (title, notes, dates, tags)
edit_project - Update project details and metadata

🔍 Management Operations

search_tasks - Search tasks by title or content
complete_task - Mark tasks as completed

💾 Backup & Restore Operations

backup_things3 - Create comprehensive backup of all Things 3 data
restore_things3 - Load backup data (analysis and reference)

Installation

Prerequisites

macOS (required for Things 3)
Things 3 application installed
Node.js 18.0.0 or higher
DXT-compatible host (Claude Desktop, etc.)

Install Dependencies

cd server
npm install

Package as DXT Extension

Since DXT CLI is not yet publicly available, create the package manually:

# Create DXT package (ZIP format)
zip -r things3-mcp-dxt-extension-v1.0.0.dxt . -x "*.git*" "*.DS_Store*" "*.dxt" ".claude/*" "reddit_post.md"

Important: Exclude .claude/ directory to avoid installation errors in Claude Desktop.

Add to Host Application

Add the extension to your MCP-compatible host's configuration:

{
  "mcpServers": {
    "things3-extended": {
      "command": "node",
      "args": ["/path/to/extension/server/index.js"]
    }
  }
}

Usage Examples

Task Management Workflow

// View what's in your inbox
await callTool("view_inbox");

// Create a new task
await callTool("create_task", {
  title: "Review quarterly reports",
  notes: "Focus on sales and marketing metrics",
  when: "today",
  tags: "work,review"
});

// Move task from today to a specific project
await callTool("move_task_to_project", {
  title: "Review quarterly reports", 
  project: "Q4 Planning"
});

// Edit the task to add a deadline
await callTool("edit_task", {
  current_title: "Review quarterly reports",
  deadline: "2024-12-31"
});

Backup & Recovery

// Create backup
await callTool("backup_things3", {
  backup_path: "/Users/username/Desktop/things3_backup.json"
});

// Analyze backup contents
await callTool("restore_things3", {
  backup_path: "/Users/username/Desktop/things3_backup.json"
});

Technical Implementation

Architecture

MCP Protocol: Uses @modelcontextprotocol/sdk for communication
AppleScript Integration: Direct interaction with Things 3 via AppleScript
URL Schemes: Leverages Things 3 URL schemes for creation operations
Error Handling: Comprehensive timeout and error management

Security Features

Input sanitization for AppleScript injection prevention
URL encoding for special characters
Timeout protection (10 second limit)
Safe string escaping

Performance Considerations

Async operations throughout
Efficient AppleScript execution
JSON parsing with fallback defaults
Memory-efficient data handling

API Reference

Task Creation Parameters

{
  title: string,        // Required
  notes: string,        // Optional
  when: string,         // Optional - "today", "tomorrow", "2024-12-31"
  deadline: string,     // Optional - Date string
  tags: string,         // Optional - Comma-separated
  list: string,         // Optional - Project/area name
  checklist: string     // Optional - Checklist items
}

Backup Data Structure

{
  timestamp: "2024-12-01T10:00:00Z",
  version: "1.0.0",
  data: {
    inbox: [...],     // Array of inbox tasks
    today: [...],     // Array of today's tasks  
    projects: [...],  // Array of projects
    areas: [...]      // Array of areas
  }
}

Troubleshooting

Common Issues

"Things 3 not responding"
- Ensure Things 3 is running
- Check macOS permissions for AppleScript
"Task not found" errors
- Search uses partial matching
- Check exact task titles
- Tasks may be in different lists
Backup/restore failures
- Verify file path permissions
- Ensure sufficient disk space
- Check JSON syntax in backup files

Debug Mode

Set NODE_ENV=development for detailed logging:

NODE_ENV=development node server/index.js

License

MIT License - See LICENSE file for details.

Repository

GitHub: https://github.com/upup666/things3-mcp-dxt-extension

Contributing

Contributions welcome! Please follow the existing code style and add tests for new features.

Issues & Support

Report issues at: https://github.com/upup666/things3-mcp-dxt-extension/issues

🚀 Ready to supercharge your Things 3 workflow with AI assistance!

Things 3 Extended