Things 3 MCP Server

A Model Context Protocol (MCP) server that connects Claude and other AI assistants to Things 3 for natural language task management.

Installation

Option 1: From PyPI (Recommended)

1. Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On macOS/Linux

2. Install the package:

pip install mcp-server-things

Option 2: From Source (Development)

1. Clone the repository:

git clone https://github.com/ebowman/mcp-server-things.git
cd mcp-server-things

2. Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On macOS/Linux

3. Install dependencies:

pip install -r requirements.txt

4. Install in development mode:

pip install -e .

Claude Desktop Configuration

For PyPI Installation

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "things": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "things_mcp"],
      "env": {
        "THINGS_MCP_LOG_LEVEL": "INFO",
        "THINGS_MCP_APPLESCRIPT_TIMEOUT": "30"
      }
    }
  }
}

For Source Installation

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "things": {
      "command": "/path/to/mcp-server-things/venv/bin/python",
      "args": ["-m", "things_mcp"],
      "env": {
        "PYTHONPATH": "/path/to/mcp-server-things/src",
        "THINGS_MCP_LOG_LEVEL": "INFO",
        "THINGS_MCP_APPLESCRIPT_TIMEOUT": "30"
      }
    }
  }
}

Notes:

• PyPI: Replace /path/to/your/venv/bin/python with your virtual environment's Python path
• Source: Replace /path/to/mcp-server-things with your actual installation path and include the PYTHONPATH
• Use the full path to the Python executable in your virtual environment
• See Configuration section below for environment variable options

Creating tasks with natural language through Claude

📚 Documentation

• User Examples - Rich examples of how to use Things 3 with AI assistants
• Architecture Overview - Technical design and implementation details
• Troubleshooting - Common issues and solutions

Features

Core Todo Operations

• Create: Add todos with full metadata (tags, deadlines, projects, notes, reminders)
• Read: Get todos by ID, project, or built-in lists (Today, Inbox, Upcoming, etc.)
• Update: Modify existing todos with partial updates
• Delete: Remove todos safely
• Search: Find todos by title, notes, or advanced filters

Project & Area Management

• Get all projects and areas with optional task inclusion
• Create new projects with initial todos
• Update project metadata and status
• Organize todos within project hierarchies

Built-in List Access

• Inbox: Capture new items
• Today: Items scheduled for today
• Upcoming: Future scheduled items
• Anytime: Items without specific dates
• Someday: Items for future consideration
• Logbook: Completed items history
• Trash: Deleted items

Advanced Features

• Reminder Support: Create todos with specific reminder times (e.g., "today@14:30")
  • Uses hybrid approach: AppleScript for regular todos, URL scheme for reminders
  • This works around AppleScript API limitation (cannot set reminder times)
• Tag Management: Full tag support with AI creation control
• Date-Range Queries: Get todos due/activating within specific timeframes
• URL Schemes: Native Things 3 URL scheme integration
• Health Monitoring: System health checks and queue status monitoring
• Error Handling: Robust error handling with configurable retries
• Logging: Structured logging with configurable levels
• Concurrency Support: Multi-client safe operation with operation queuing
• Input Validation: Configurable limits for titles, notes, and tags

Requirements

• macOS: This server requires macOS (tested on macOS 12+)
• Things 3: Things 3 must be installed and accessible
• Python: Python 3.8 or higher
• Permissions: AppleScript permissions for Things 3 access

Quick Start

Once installed, Claude (or other MCP clients) can automatically discover and use all available tools. No additional setup required.

Configuration

The server uses environment variables for configuration. You can set these variables in three ways:

1. System environment variables
2. A .env file (automatically loaded from the current directory)
3. A custom .env file specified with --env-file

Using the .env File

1. Review the example configuration:

   cat .env.example

2. Create your own .env file:

   cp .env.example .env
   # Edit .env to customize settings

3. Or use a custom location:

   cp .env.example ~/my-things-config.env
   python -m things_mcp --env-file ~/my-things-config.env

Key Configuration Options

# Server identification
THINGS_MCP_SERVER_NAME=things3-mcp-server
THINGS_MCP_SERVER_VERSION=1.0.0

# AppleScript execution
THINGS_MCP_APPLESCRIPT_TIMEOUT=30.0       # Timeout in seconds (1-300)
THINGS_MCP_APPLESCRIPT_RETRY_COUNT=3      # Retry attempts (0-10)

# Tag management - Control AI tag creation
THINGS_MCP_AI_CAN_CREATE_TAGS=false       # false = AI can only use existing tags
THINGS_MCP_TAG_VALIDATION_CASE_SENSITIVE=false

# Logging
THINGS_MCP_LOG_LEVEL=INFO                 # DEBUG, INFO, WARNING, ERROR, CRITICAL
THINGS_MCP_LOG_FILE_PATH=/path/to/file.log # Optional: log to file instead of console

# Validation limits
THINGS_MCP_MAX_TITLE_LENGTH=500
THINGS_MCP_MAX_NOTES_LENGTH=10000
THINGS_MCP_MAX_TAGS_PER_ITEM=20
THINGS_MCP_SEARCH_RESULTS_LIMIT=100

Command Line Options

The server supports several command-line options:

# Start with debug logging
python -m things_mcp --debug

# Use a custom .env file
python -m things_mcp --env-file ~/my-config.env

# Check system health
python -m things_mcp --health-check

# Test AppleScript connectivity
python -m things_mcp --test-applescript

# Show version
python -m things_mcp --version

# Customize timeout and retry settings
python -m things_mcp --timeout 60 --retry-count 5

Claude Desktop Environment Variables

You can set environment variables directly in your Claude Desktop configuration:

{
  "mcpServers": {
    "things": {
      "env": {
        "THINGS_MCP_LOG_LEVEL": "DEBUG",
        "THINGS_MCP_AI_CAN_CREATE_TAGS": "true",
        "THINGS_MCP_APPLESCRIPT_TIMEOUT": "60"
      }
    }
  }
}

Available MCP Tools

Todo Management

• get_todos(project_uuid?, include_items?) - List todos
• add_todo(title, ...) - Create new todo with optional reminder time
• update_todo(id, ...) - Update existing todo
• get_todo_by_id(todo_id) - Get specific todo
• delete_todo(todo_id) - Delete todo

Project Management

• get_projects(include_items?) - List projects
• add_project(title, ...) - Create new project
• update_project(id, ...) - Update existing project

Area Management

• get_areas(include_items?) - List areas

List Access

• get_inbox() - Get Inbox todos
• get_today() - Get Today's todos
• get_upcoming() - Get upcoming todos
• get_anytime() - Get Anytime todos
• get_someday() - Get Someday todos
• get_logbook(limit?, period?) - Get completed todos
• get_trash() - Get trashed todos

Date-Range Queries

• get_due_in_days(days) - Get todos due within specified days
• get_activating_in_days(days) - Get todos activating within days
• get_upcoming_in_days(days) - Get todos due or activating within days

Search & Tags

• search_todos(query) - Basic search
• search_advanced(...) - Advanced search with filters
• get_tags(include_items?) - List tags
• create_tag(name) - Create a new tag
• get_tagged_items(tag) - Get items with specific tag
• add_tags(todo_id, tags) - Add tags to a todo
• remove_tags(todo_id, tags) - Remove tags from a todo
• get_recent(period) - Get recently created items

Bulk Operations

• move_record(record_id, to_parent_uuid) - Move single record
• bulk_move_records(record_ids, to_parent_uuid) - Move multiple records

System & Utilities

• health_check() - Check server and Things 3 status
• queue_status() - Check operation queue status and statistics
• get_server_capabilities() - Get server features and configuration
• get_usage_recommendations() - Get usage tips and best practices
• context_stats() - Get context-aware response statistics

Troubleshooting

Common Issues

Permission Denied Errors

# Grant AppleScript permissions to your terminal/IDE
# System Preferences > Security & Privacy > Privacy > Automation
# Enable access for your terminal application to control Things 3

Things 3 Not Found

# Verify Things 3 is installed and running
python -m things_mcp.main --health-check

# Check if Things 3 is in Applications folder
ls /Applications/ | grep -i things

Connection Timeouts

# Increase timeout value via environment variable
export THINGS_MCP_APPLESCRIPT_TIMEOUT=60

# Or in your .env file
THINGS_MCP_APPLESCRIPT_TIMEOUT=60

Debug Mode

# Enable debug logging
python -m things_mcp.main --debug

# Check logs
tail -f things_mcp.log

Health Diagnostics

# Comprehensive health check
python -m things_mcp.main --health-check

# Test specific components
python -m things_mcp.main --test-applescript

Performance

• Startup Time: Less than 2 seconds
• Response Time: Less than 500ms for most operations
• Memory Usage: 15MB baseline, 50MB under concurrent load
• Concurrent Requests: Serialized write operations to prevent conflicts
• Throughput: Multiple operations per second depending on complexity
• Queue Processing: Less than 50ms latency for operation enqueuing

Security

• No network access required (local AppleScript only)
• No data stored outside of Things 3
• Minimal system permissions needed
• Secure AppleScript execution with timeouts
• Input validation on all parameters

Contributing

Contributions are welcome! Please follow these guidelines:

• Set up a virtual environment and install dependencies
• Follow existing code style and patterns
• Add tests for new features
• Submit pull requests with clear descriptions

Documentation

• Troubleshooting Guide - Common issues and solutions
• Development Roadmap - Implementation status and missing features

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

Roadmap

Phase 1: Core Stability (Current)

• Complete MCP tool implementation (Completed)
• Robust error handling and logging (Completed)
• Comprehensive testing suite (Completed)
• Documentation and examples (Completed)

Phase 2: Enhanced Features

• Multi-client concurrency support with operation queuing (Completed)
• Configurable tag creation policies (Completed)
• Reminder support with datetime scheduling (Completed)
• Date-range query tools (Completed)
• Bulk move operations (Completed)
• Real-time sync with Things 3 changes (Planned)
• Advanced natural language processing (Planned)
• Integration with calendar and email (Planned)

Phase 3: Advanced Integration

• Multi-user support (Planned)
• API rate limiting (Planned)
• Webhook support (Planned)
• Analytics and reporting (Planned)

---

Built for the Things 3 and MCP community.