Troubleshooting Guide

September 10, 2026 · View on GitHub

Common issues and solutions for the Things 3 MCP Server.

For the macOS TCC/Automation/Full-Disk-Access dialogs specifically (why the "app data" prompt recurs and headless setup), see docs/MACOS_PERMISSIONS.md.

Common Issues

Things 3 Integration

Permission Denied / Automation Access

Problem: System hasn't granted automation permissions

Symptoms:

error "Not authorized to send Apple events to Things3." number -1743

Solution:

  1. Open System Settings → Privacy & Security
  2. Click Privacy tab → Automation
  3. Find your terminal/IDE in the list
  4. Check the box next to Things3
  5. Restart your terminal/IDE

Alternative Reset:

# Reset automation permissions (requires admin)
sudo tccutil reset AppleEvents com.apple.Terminal

Things 3 Not Found

Problem: Things 3 not installed or not accessible

Check:

# Verify Things 3 is installed
ls -la /Applications/Things3.app

# Test direct AppleScript
osascript -e 'tell application "Things3" to get name'

Solutions:

  1. Install Things 3 from Mac App Store
  2. Launch Things 3 manually
  3. Verify app name is "Things3" (not "Things 3")

Claude Desktop Integration

Configuration Not Loading

Problem: Claude Desktop can't find MCP configuration

Check Config:

# Validate JSON syntax
python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

Correct Configuration:

{
  "mcpServers": {
    "things": {
      "command": "python",
      "args": ["-m", "things_mcp.main"]
    }
  }
}

MCP Server Failed to Start

Test Manually:

# Verify package installation
python -c "import things_mcp; print('OK')"

Use Absolute Path:

{
  "mcpServers": {
    "things": {
      "command": "/usr/local/bin/python3",
      "args": ["-m", "things_mcp.main"]
    }
  }
}

Performance Issues

Slow Operations

Solutions:

  1. Restart Things 3 (it can become sluggish)
  2. Check available system memory
  3. Reduce concurrent operations if needed

AppleScript Timeouts

Increase Timeout:

export THINGS_MCP_TIMEOUT=60

Error Messages Reference

ErrorCauseSolution
"Can't get..."Object doesn't existVerify item ID in Things 3
"Invalid date format"Wrong date formatUse YYYY-MM-DD format
"Operation failed after 3 retries"AppleScript failuresRestart Things 3

Advanced Diagnostics

Enable Debug Logging

export THINGS_MCP_LOG_LEVEL=DEBUG
python -m things_mcp.main

Test AppleScript Directly

osascript -e 'tell application "Things3" to get name of every to do of list "Today"'

Getting Help

Before Asking for Help

  1. Check GitHub Issues
  2. Review this troubleshooting guide
  3. Verify Things 3 and Python are properly installed

When Requesting Help

Include:

  • macOS version
  • Python version (python --version)
  • Things 3 version
  • Complete error messages
  • Steps to reproduce

Contact