Things 3 Extended

A desktop extension for the Things 3 task manager, providing advanced features like task movement, editing, and backups.

GitHub

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

  1. "Things 3 not responding"

    • Ensure Things 3 is running
    • Check macOS permissions for AppleScript

  2. "Task not found" errors

    • Search uses partial matching
    • Check exact task titles
    • Tasks may be in different lists

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

関連サーバー