MCP Server for Things3

A robust MCP (Model Context Protocol) server providing comprehensive integration with Things3, allowing you to create, manage, and search tasks and projects through the MCP protocol. Features improved error handling, secure URL encoding, and enhanced AppleScript integration.

Features

• ✅ Create Projects: Create new projects in Things3 with full metadata support
• ✅ Create Todos: Create new to-dos with detailed properties including checklists, tags, and dates
• ✅ View Tasks: List tasks from inbox, today's list, or all projects
• ✅ Complete Tasks: Mark todos as completed by searching for their title
• ✅ Search Functionality: Search through all todos by title or content
• ✅ Robust Error Handling: Comprehensive validation and error recovery
• ✅ Secure URL Encoding: Proper handling of special characters and unicode
• ✅ AppleScript Integration: Safe, non-JSON string concatenation approach

Installation

Quick Start

# Clone the repository
git clone https://github.com/drjforrest/mcp-things3.git
cd mcp-things3

# Install dependencies
npm install

# Build the server
npm run build

Prerequisites

• macOS: This server only works on macOS due to AppleScript dependencies
• Things3: Must be installed and running
• Node.js: Version 14 or higher
• NPM: For package management

Tools Available

create-todo

Creates a new to-do in Things3 with comprehensive options.

Parameters:

• title (required): The title of the to-do
• notes (optional): Detailed notes for the to-do
• when (optional): When to schedule the task (today, tomorrow, someday, anytime, or specific date)
• deadline (optional): Due date for the task
• tags (optional): Array of tag names to apply
• checklist (optional): Array of checklist items
• project (optional): Name of the project to add the to-do to
• area (optional): Name of the area to assign

create-project

Creates a new project in Things3.

Parameters:

• title (required): The title of the project
• notes (optional): Detailed notes for the project
• when (optional): When to start the project
• deadline (optional): Due date for the project
• tags (optional): Array of tag names to apply
• area (optional): Name of the area to assign

view-inbox

Lists all tasks currently in the Things3 inbox.

No parameters required

view-today

Lists all tasks scheduled for today.

No parameters required

view-projects

Lists all projects in Things3.

No parameters required

complete-todo

Marks a to-do as completed by searching for its title.

Parameters:

• title (required): The title of the to-do to complete

search-todos

Searches for to-dos by title or content.

Parameters:

• query (required): Search term to look for in to-do titles and notes

Integration with Claude

Setup in Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "things3": {
      "command": "node",
      "args": ["/path/to/mcp-things3/build/index.js"]
    }
  }
}

Example Usage with Claude

Once configured, you can interact with Things3 naturally through Claude:

You: "Add a task to review the quarterly budget, due next Friday, and tag it as urgent"

Claude: I'll create a task for you to review the quarterly budget. Let me add it to Things3 with the appropriate details.

[Claude will use the create-todo tool to add the task with the specified parameters]

Configuration

Environment Variables

The server supports optional configuration through environment variables:

• THINGS3_DEBUG: Set to true to enable detailed logging
• THINGS3_TIMEOUT: AppleScript execution timeout in milliseconds (default: 5000)

AppleScript Permissions

When first running the server, macOS will prompt for AppleScript permissions. You must grant these permissions for the server to interact with Things3.

Architecture

Core Components

• Server: MCP protocol server handling client connections
• Tools: Individual tool implementations for each Things3 operation
• AppleScript Interface: Secure wrapper for executing AppleScript commands
• URL Encoder: Handles special characters and unicode in Things3 URLs
• Error Handler: Comprehensive error catching and user-friendly messages

Security Features

• Input Sanitization: All user inputs are properly escaped
• AppleScript Injection Prevention: Uses parameter binding instead of string concatenation
• Permission Validation: Checks Things3 availability before operations
• Error Isolation: Individual tool failures don't crash the entire server

Development

Setup Development Environment

# Install dependencies
npm install

# Run in development mode with auto-reload
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Type checking
npm run type-check

Project Structure

mcp-things3/
├── src/
│   ├── index.ts          # Main server entry point
│   ├── tools/            # Individual MCP tools
│   ├── applescript/      # AppleScript interface
│   ├── types/            # TypeScript type definitions
│   └── utils/            # Utility functions
├── tests/                # Test files
├── build/                # Compiled JavaScript
└── package.json

Adding New Tools

1. Create a new tool file in src/tools/
2. Implement the Tool interface
3. Add comprehensive error handling
4. Include input validation
5. Add tests for the new functionality
6. Update this README

Troubleshooting

Common Issues

"Things3 is not running"

• Ensure Things3 application is open
• Check that Things3 has finished loading completely

"Permission denied for AppleScript"

• Go to System Preferences → Security & Privacy → Privacy → Automation
• Enable permissions for your terminal/Node.js to control Things3

"Command not found" errors

• Verify Node.js installation: node --version
• Check that the build directory exists: npm run build
• Ensure correct path in Claude Desktop configuration

Unicode/Special Character Issues

• The server automatically handles URL encoding
• If issues persist, check the THINGS3_DEBUG environment variable

Debug Mode

Enable debug logging to troubleshoot issues:

THINGS3_DEBUG=true node build/index.js

This will output detailed information about:

• AppleScript execution
• URL encoding processes
• Error stack traces
• MCP protocol messages

Testing AppleScript Integration

You can test the AppleScript integration directly:

# Test basic Things3 connectivity
osascript -e 'tell application "Things3" to get name of first to do of list "Inbox"'

# Test URL scheme handling
open "things:///add?title=Test%20Task"

License

MIT License - see LICENSE file for details.

Changelog

v2.0.0

• ✅ Complete rewrite with improved error handling
• ✅ Secure URL encoding for special characters
• ✅ Enhanced AppleScript integration
• ✅ Comprehensive input validation
• ✅ Better TypeScript types and interfaces

v1.0.0

• ✅ Initial release
• ✅ Basic CRUD operations for todos and projects
• ✅ MCP protocol compliance
• ✅ AppleScript integration

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

For bugs and feature requests, please create an issue on GitHub.