# Things3 MCP Tools

Except for specific skills and scripts that I added, I would recommend this MCP instead: https://github.com/hald/things-mcp

---

Model Context Protocol (MCP) tools for Things3 task management with optional Notion integration. Provides comprehensive automation for Things3 via AppleScript and direct SQLite access, with Claude Code skills for workflow guidance.

## Demo

https://github.com/user-attachments/assets/42e9f9a0-28b8-40d1-98d6-5d6c7457f23f

## What This Provides

**MCP Tools for Things3:**
- Complete task management (create, read, update, delete, search)
- Direct SQLite access for fast search across titles and notes
- AppleScript integration for reliable task manipulation
- Bulk operations (tagging, moving, completing tasks)
- Project and area management

**Optional Notion Integration:**
- Migrate Things3 inbox items to Notion
- Cross-system workflow patterns via Claude skills

**Claude Code Skills:**
- Auto-loading workflow guidance for productivity tasks
- Personal taxonomy integration for work contexts
- Best practices and automation patterns

## Repository Structure

```
.
├── .claude/skills/          # Claude Code auto-loading skills
│   ├── things3-productivity/    # Things3 workflows and patterns
│   ├── notion-workflows/        # Notion organization patterns
│   └── productivity-integration/ # Cross-system workflows
├── tooling/                 # MCP server and tools
│   ├── mcp-server/             # MCP server configuration
│   └── scripts/                # Tool implementations
└── private-prefs.example.json  # Template for personal preferences
```

## Setup

### Prerequisites

- macOS with Things3 installed
- Python 3.11+
- Claude Code (for skills integration)
- Optional: Notion account (for Notion integration features)

### Installation

1. **Install dependencies:**
   ```bash
   cd tooling
   pip install -r requirements.txt
   ```

2. **Configure MCP server in Claude Code:**
   Add to your Claude Code MCP settings:
   ```json
   {
     "mcpServers": {
       "things3-notion": {
         "command": "node",
         "args": ["/path/to/tooling/mcp-server/build/index.js"],
         "env": {
           "SCRIPTS_DIR": "/path/to/tooling/scripts"
         }
       }
     }
   }
   ```

3. **Optional: Set up personal preferences:**
   ```bash
   cp private-prefs.example.json private-prefs/personal-taxonomy.json
   # Edit with your tags, areas, and preferences
   ```
### Adding Notion MCP (Optional)

You can use both Things3 and Notion MCP tools together in Claude Code. You can read about the Notion MCP [here](https://developers.notion.com/docs/mcp).

## Available Tools

### Task Management

- **`read_tasks`** - List and filter tasks by list, area, project, tags, priority, or status
- **`search_tasks`** - Fast SQLite search across task titles and notes
- **`create_task`** - Create new tasks with tags, scheduling, and project assignment
- **`edit_task`** - Modify existing tasks (title, notes, tags, scheduling, completion)
- **`delete_tasks`** - Move tasks to trash (with confirmation)
- **`complete_tasks`** - Mark tasks as completed
- **`move_tasks`** - Move tasks between lists (Today, Anytime, Someday, etc.)

### Organization

- **`add_tags`** / **`remove_tags`** - Bulk tag management
- **`list_areas`** / **`list_projects`** / **`list_tags`** - Browse organizational structure
- **`create_project`** / **`create_area`** - Create new organizational containers
- **`get_project_tasks`** - View all tasks within a project
- **`get_selected`** - Get currently selected tasks from Things3 UI

### Integration

- **`migrate_inbox_to_notion`** - Transfer Things3 inbox items to Notion blocks

## Usage Examples

### Search for tasks
```python
# Find task by partial title
search_tasks(query="meeting", when="today")

# Search with filters
search_tasks(query="bug", area="Work", tags=["urgent"])
```

### Read tasks from a list
```python
# Get today's tasks
read_tasks(when="today")

# Filter by area and priority
read_tasks(when="today", area="Work", min_priority=7)

# List projects in an area
read_tasks(area="Work", list_projects=True)
```

### Create and manage tasks
```python
# Create a task
create_task(
    title="Review PR",
    notes="Check for test coverage",
    when="today",
    tags=["code-review"],
    area="Work"
)

# Edit a task
edit_task(
    task_uuid="abc-123",
    tags=["urgent", "code-review"],
    when="today"
)

# Bulk operations
complete_tasks(task_uuids=["abc-123", "def-456"])
add_tags(task_uuids=["abc-123"], tags=["waiting"])
```

## Personal Preferences (Optional but Recommended)

The tools support personal taxonomy for automatic context injection. Create `private-prefs/personal-taxonomy.json` based on the example template to define:

- **Work tags**: Your work identification tag (e.g., "WORK", "CLIENT") - tools automatically recognize tasks with this tag as work-related
- **Work areas**: Your professional focus areas
- **Priority system**: Your 1-9 priority preferences
- **Common project patterns**: Typical project structures
- **Notion integration mappings**: Block IDs for migration

**Important**: Tools like `read_tasks` and `search_tasks` use the `work_tag` from your personal preferences to identify work tasks. Without preferences, they default to looking for a "WORK" tag.

Example `private-prefs/personal-taxonomy.json`:
```json
{
  "things3": {
    "work_classification": {
      "work_tag": "YOUR_WORK_TAG",
      "work_areas": ["Your Work Area"]
    }
  }
}
```

Personal preferences are automatically loaded by tools when available, but all tools work without them using sensible defaults.

## Claude Code Skills

Skills in `.claude/skills/` provide auto-loading workflow guidance:

- **things3-productivity** - Task management patterns, query strategies, automation workflows
- **notion-workflows** - Workspace organization, content reuse patterns
- **productivity-integration** - Cross-system automation strategies
- **inbox-processing.example** - Example workflow for batch inbox processing (see directory for customization guide)

Skills reference personal preferences automatically to provide contextual guidance.

**Note**: You may have private skills in `.claude/skills/` that are gitignored (e.g., `inbox-processing/` with personal workflow patterns). These won't appear in the repository but will be available locally for your use.

## Development

### Running Tools Directly

Tools can be executed from command line for testing:

```bash
cd tooling/scripts
python3 read_tasks.py --when today --json
python3 search_tasks.py "meeting" --when today
python3 create_task.py --title "Test task" --when today
```

### Adding New Tools

1. Create script in `tooling/scripts/`
2. Add tool definition to `tooling/mcp-server/tools-manifest.json`
3. Restart Claude Code MCP server

## Architecture

- **AppleScript layer**: Reliable task manipulation via Things3's native API
- **things.py**: Direct SQLite access for fast search operations
- **MCP server**: Standard interface for Claude Code integration
- **Skills**: Auto-loading workflow guidance and personal context