# Just Claude Things

An MCP server that lets Claude read and write your Things 3 tasks on macOS via AppleScript.

## Requirements

- macOS
- [Things 3](https://culturedcode.com/things/) installed and running
- Node.js 18+
- When first used, macOS will prompt you to grant Automation permissions (System Settings → Privacy & Security → Automation)

## Quick Start

### Claude Desktop

Add to your `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "things3": {
      "command": "npx",
      "args": ["-y", "things3-mcp"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add things3 -- npx -y things3-mcp
```

## Available Tools

### Read

#### `get_todos`

List todos with optional filters.

```json
{ "status": "today" }
{ "tag": "work", "status": "anytime" }
{ "search": "meeting notes" }
{ "projectId": "ABC123" }
```

| Parameter   | Type   | Description                                                        |
| ----------- | ------ | ------------------------------------------------------------------ |
| `status`    | string | Filter by list: `inbox`, `today`, `upcoming`, `anytime`, `someday`, `logbook` |
| `projectId` | string | Filter by project ID                                               |
| `areaId`    | string | Filter by area ID                                                  |
| `tag`       | string | Filter by tag name                                                 |
| `search`    | string | Search todo titles and notes                                       |

#### `get_todo`

Get a single todo by ID with full details.

```json
{ "id": "ABC123" }
```

#### `get_projects`

List all projects with status, area, and tags. No parameters.

#### `get_areas`

List all areas. No parameters.

#### `get_tags`

List all tags. No parameters.

### Write

#### `create_todo`

Create a new todo.

```json
{
  "title": "Review PR #42",
  "notes": "Check the error handling changes",
  "when": "today",
  "tags": ["work"],
  "checklistItems": ["Read the diff", "Run tests locally", "Leave review"]
}
```

| Parameter        | Type     | Description                                                         |
| ---------------- | -------- | ------------------------------------------------------------------- |
| `title`          | string   | **Required.** Title of the todo                                     |
| `notes`          | string   | Notes/description                                                   |
| `when`           | string   | `today`, `evening`, `tomorrow`, `someday`, or date (`YYYY-MM-DD`)   |
| `deadline`       | string   | Deadline date (`YYYY-MM-DD`)                                        |
| `tags`           | string[] | Tag names to apply                                                  |
| `projectId`      | string   | Project ID to add this todo to                                      |
| `heading`        | string   | Heading within the project                                          |
| `checklistItems` | string[] | Checklist items                                                     |

#### `create_project`

Create a new project.

```json
{
  "title": "Q2 Planning",
  "notes": "Quarterly goals and milestones",
  "tags": ["work"],
  "when": "2025-04-01",
  "deadline": "2025-06-30"
}
```

| Parameter  | Type     | Description                                                       |
| ---------- | -------- | ----------------------------------------------------------------- |
| `title`    | string   | **Required.** Title of the project                                |
| `notes`    | string   | Notes/description                                                 |
| `areaId`   | string   | Area ID to assign to                                              |
| `tags`     | string[] | Tag names                                                         |
| `when`     | string   | `today`, `evening`, `tomorrow`, `someday`, or date (`YYYY-MM-DD`) |
| `deadline` | string   | Deadline date (`YYYY-MM-DD`)                                      |

#### `update_todo`

Update an existing todo by ID.

```json
{
  "id": "ABC123",
  "when": "tomorrow",
  "tags": ["urgent"]
}
```

| Parameter  | Type     | Description                                                       |
| ---------- | -------- | ----------------------------------------------------------------- |
| `id`       | string   | **Required.** Todo ID                                             |
| `title`    | string   | New title                                                         |
| `notes`    | string   | New notes (appended to existing)                                  |
| `when`     | string   | `today`, `evening`, `tomorrow`, `someday`, or date (`YYYY-MM-DD`) |
| `deadline` | string   | New deadline (`YYYY-MM-DD`)                                       |
| `tags`     | string[] | Tags to add                                                       |

#### `complete_todo`

Mark a todo as complete.

```json
{ "id": "ABC123" }
```

#### `delete_todo`

Move a todo to Trash (recoverable from Things 3 Trash).

```json
{ "id": "ABC123" }
```

## License

MIT