# hae-mcp

MCP server for **hae** — a self-hosted GTD task management app. Gives Claude full access to your hae instance: projects, cards, columns, checklists, comments, labels, organisations, notifications, users, and AI features.

**Version:** 1.3.2 | 100% API coverage — 57 tools | [hae-app](../hae-app) · [hae-api](../hae-api)

## Requirements

- Node.js 18+
- A running [hae-api](https://github.com/bzhzion/hae-api) instance

## Installation

### Via npx (recommended — no install needed)

```json
{
  "mcpServers": {
    "hae": {
      "command": "npx",
      "args": ["-y", "@breizhzion/hae-mcp"],
      "env": {
        "HAE_URL": "http://your-server:3000",
        "HAE_TOKEN": "your-jwt-token"
      }
    }
  }
}
```

### Via local clone

```bash
git clone https://github.com/bzhzion/hae-mcp
cd hae-mcp
npm install
npm run build
```

```json
{
  "mcpServers": {
    "hae": {
      "command": "node",
      "args": ["/path/to/hae-mcp/dist/index.js"],
      "env": {
        "HAE_URL": "http://localhost:3000",
        "HAE_EMAIL": "user@example.com",
        "HAE_PASSWORD": "yourpassword"
      }
    }
  }
}
```

### Where to put the config

| Client | Config file |
|--------|-------------|
| Claude Code (global) | `~/.claude/settings.json` |
| Claude Desktop (Mac) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |

## Authentication

`HAE_TOKEN` takes priority. If absent, auto-login with `HAE_EMAIL` + `HAE_PASSWORD`.

| Variable | Description |
|----------|-------------|
| `HAE_URL` | hae-api base URL. Default: `http://localhost:3000` |
| `HAE_TOKEN` | JWT token — recommended for production |
| `HAE_EMAIL` | Email for auto-login |
| `HAE_PASSWORD` | Password for auto-login |

To get a token manually:

```bash
curl -X POST http://your-server:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"yourpassword"}'
# → {"token":"eyJ..."}
```

## Tools

### Projects

| Tool | Description |
|------|-------------|
| `hae_list_projects` | List all accessible projects with their columns |
| `hae_get_project` | Get a project by ID |
| `hae_create_project` | Create a new project |
| `hae_update_project` | Update project name or description |
| `hae_delete_project` | Delete a project permanently |
| `hae_assign_project_org` | Assign a project to an organisation |
| `hae_add_project_member` | Add a user to a project |
| `hae_update_project_member` | Change a project member's role |
| `hae_remove_project_member` | Remove a member from a project |

#### `hae_create_project`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | yes | Project name |
| `description` | string | no | Optional description |

#### `hae_update_project`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | yes | Project ID |
| `name` | string | no | New name |
| `description` | string | no | New description |

#### `hae_assign_project_org`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | yes | Project ID |
| `org_id` | string | yes | Organisation ID |

#### `hae_add_project_member` / `hae_update_project_member`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | yes | Project ID |
| `user_id` | string | yes | User ID (use `hae_search_users` to find it) |
| `role` | `owner` \| `member` | no/yes | Role |

---

### Columns

| Tool | Description |
|------|-------------|
| `hae_create_column` | Create a custom column in a project |
| `hae_update_column` | Rename a column |
| `hae_delete_column` | Delete a column (cards moved to Trash) |

#### `hae_create_column`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | yes | Project ID |
| `name` | string | yes | Column name |

---

### Cards

| Tool | Description |
|------|-------------|
| `hae_list_cards` | List cards in a column (with checklist progress + comment count) |
| `hae_get_card` | Get full card details |
| `hae_create_card` | Create a card in a column |
| `hae_update_card` | Update or move a card |
| `hae_duplicate_card` | Duplicate a card |
| `hae_delete_card` | Trash or permanently delete a card |
| `hae_get_card_activities` | Get the activity log of a card |
| `hae_stopwatch_start` | Start the stopwatch on a card |
| `hae_stopwatch_stop` | Stop the stopwatch on a card |
| `hae_add_card_member` | Assign a user to a card |
| `hae_remove_card_member` | Unassign a user from a card |
| `hae_add_card_label` | Add a label to a card |
| `hae_remove_card_label` | Remove a label from a card |
| `hae_subscribe_card` | Subscribe to notifications for a card |
| `hae_unsubscribe_card` | Unsubscribe from notifications for a card |

#### `hae_create_card`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `column_id` | string | yes | Target column ID |
| `title` | string | yes | Card title |
| `description` | string | no | Description — Markdown supported |
| `due_date` | number | no | Due date as Unix timestamp in ms |

#### `hae_update_card`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | yes | Card ID |
| `title` | string | no | New title |
| `description` | string | no | New description (Markdown) |
| `due_date` | number or null | no | New due date (Unix ms), or `null` to clear |
| `column_id` | string | no | Target column ID — moves the card |

#### `hae_delete_card`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | yes | Card ID |
| `permanent` | boolean | no | `true` = hard delete. Default: `false` (moves to Trash) |

---

### Comments

| Tool | Description |
|------|-------------|
| `hae_list_comments` | List all comments on a card |
| `hae_add_comment` | Add a comment to a card |
| `hae_update_comment` | Edit a comment |
| `hae_delete_comment` | Delete a comment |

#### `hae_add_comment` / `hae_update_comment`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `card_id` / `id` | string | yes | Card ID or Comment ID |
| `content` | string | yes | Comment text |

---

### Checklists

| Tool | Description |
|------|-------------|
| `hae_add_checklist` | Add a checklist to a card |
| `hae_update_checklist` | Rename a checklist |
| `hae_delete_checklist` | Delete a checklist and all its items |
| `hae_add_checklist_item` | Add an item to a checklist |
| `hae_toggle_checklist_item` | Mark an item done or undone |
| `hae_delete_checklist_item` | Delete a checklist item |

#### `hae_add_checklist_item`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `checklist_id` | string | yes | Checklist ID |
| `content` | string | yes | Item text |

#### `hae_toggle_checklist_item`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `item_id` | string | yes | Checklist item ID |
| `is_done` | boolean | yes | `true` = done, `false` = undone |

---

### Labels

| Tool | Description |
|------|-------------|
| `hae_list_labels` | List all labels in a project |
| `hae_create_label` | Create a label |
| `hae_update_label` | Update a label name or color |
| `hae_delete_label` | Delete a label |

#### `hae_create_label`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | yes | Project ID |
| `name` | string | yes | Label name |
| `color` | string | yes | Hex color, e.g. `#FF5733` |

---

### Organisations

| Tool | Description |
|------|-------------|
| `hae_list_orgs` | List all organisations the current user belongs to |
| `hae_get_org` | Get organisation details: members and projects |
| `hae_create_org` | Create an organisation |
| `hae_update_org` | Update organisation name or description |
| `hae_delete_org` | Delete an organisation |
| `hae_add_org_member` | Add a user to an organisation |
| `hae_update_org_member` | Change a member's role |
| `hae_remove_org_member` | Remove a member from the organisation |

#### `hae_add_org_member` / `hae_update_org_member`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | yes | Organisation ID |
| `user_id` | string | yes | User ID |
| `role` | `owner` \| `admin` \| `member` | no/yes | Role |

---

### Notifications

| Tool | Description |
|------|-------------|
| `hae_list_notifications` | List notifications for the current user |
| `hae_mark_notification_read` | Mark a notification as read |
| `hae_mark_all_notifications_read` | Mark all notifications as read |

---

### Users

| Tool | Description |
|------|-------------|
| `hae_get_me` | Get the current user's profile |
| `hae_update_me` | Update display name |
| `hae_change_password` | Change the current user's password |
| `hae_search_users` | Search a user by exact email — useful to find IDs |

#### `hae_search_users`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | yes | Exact email address to look up |

> **Note**: Avatar upload (`POST /api/users/me/avatar`) is multipart binary — available in the app only, not via MCP.

#### `hae_change_password`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `current_password` | string | yes | Current password |
| `new_password` | string | yes | New password (min 8 characters) |

---

### AI

| Tool | Description |
|------|-------------|
| `hae_ai_parse_tasks` | Parse free-form text into structured cards using AI |
| `hae_ai_generate_checklist` | Generate a checklist for a card using AI |
| `hae_ai_summarize_card` | Summarize a card (description + comments + activities) |

#### `hae_ai_parse_tasks`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | yes | Project ID where cards will be created |
| `text` | string | yes | Free-form text to parse into tasks |

---

### Admin *(requires admin role)*

| Tool | Description |
|------|-------------|
| `hae_admin_list_users` | List all users on the server |
| `hae_admin_update_user` | Change a user's role or enable/disable their account |
| `hae_admin_delete_user` | Permanently delete a user account |

#### `hae_admin_update_user`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | yes | User ID |
| `role` | `admin` \| `user` | no | New role |
| `is_active` | boolean | no | `true` = active, `false` = disabled |

---

### User preferences

| Tool | Description |
|------|-------------|
| `hae_get_prefs` | Get the current user's preferences (key/value store) |
| `hae_set_prefs` | Set one or more preferences |

#### `hae_set_prefs`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prefs` | object | yes | Key/value pairs, e.g. `{ "theme": "dark", "lang": "fr" }` |

---

## Example prompts

```
List my projects and show me what's in the URGENT column.
```
```
Create a card "Fix login bug" in the NEXT column of project X with description:
"## Steps\n- Check JWT expiry\n- Test on mobile" and due date in 2 days.
```
```
Move card abc123 to the SOMEDAY column.
```
```
Add a "Definition of Done" checklist to card abc123 with 3 items:
unit tests passing, code reviewed, deployed to staging.
```
```
Search for user "alice" and add her to project X as member.
```
```
Generate a checklist for card abc123 using AI.
```
```
Mark all my notifications as read.
```
```
Parse this text into tasks in project X:
"Call client Monday, prepare slides for Thursday demo, review PR from Bob"
```

## Development

```bash
git clone https://github.com/bzhzion/hae-mcp
cd hae-mcp
npm install
npm run dev    # tsx watch — hot reload
npm run build  # compile to dist/
```

Test with the official MCP inspector:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## Publishing

```bash
npm run build
npm publish --access public
```

## License

MIT — [Breizhzion](https://github.com/bzhzion)