# habitca-mcp

A small Model Context Protocol server that exposes the [Habitica](https://habitica.com) v3 API as MCP tools, so MCP-aware AI assistants (Claude Code, Hermes Agent, Cursor, etc.) can read and update your Habitica tasks, habits, dailies, rewards, pets, inventory and notifications.

This is a clean rewrite of the [original by iBreaker](https://github.com/iBreaker/habitica-mcp-server) — same surface, no axios/zod/i18n, single-file Node, English-only output.

## Install

```sh
git clone https://github.com/hxlair/habitca_mcp.git
cd habitca_mcp
npm install
```

Node 18 or newer is required (uses the built-in `fetch`).

## Auth

You need your Habitica API credentials:

1. Open https://habitica.com/user/settings/api
2. Copy your **User ID** and **API Token**

Export them in the shell that will launch the server:

```sh
export HABITICA_USER_ID=...
export HABITICA_API_TOKEN=...
```

Optional:

```sh
export HABITICA_APP_ID=my-mcp-client      # sent as x-client header for Habitica analytics
```

## Run

```sh
npm start
# or
./index.js
```

The server speaks MCP over stdio. It logs `habitca-mcp ready` to stderr once connected.

## Wire into an MCP client

### Claude Code / Hermes Agent / Cursor

Add to the client's MCP config:

```json
{
  "mcpServers": {
    "habitca": {
      "command": "node",
      "args": ["/absolute/path/to/habitca_mcp/index.js"],
      "env": {
        "HABITICA_USER_ID": "...",
        "HABITICA_API_TOKEN": "..."
      }
    }
  }
}
```

For Hermes specifically:

```sh
hermes mcp add habitca \
  --env HABITICA_USER_ID=... \
  --env HABITICA_API_TOKEN=... \
  -- node /absolute/path/to/habitca_mcp/index.js
```

## Tools

| Tool | Purpose |
|---|---|
| `get_user_profile` | Full user document |
| `get_stats` | HP / MP / XP / level / gold / class |
| `get_tasks` | List tasks (optionally filter by `habits` / `dailys` / `todos` / `rewards` / `completedTodos`) |
| `get_task` | Fetch one task by id |
| `create_task` | Create habit/daily/todo/reward |
| `update_task` | Update a task's fields |
| `score_task` | Score a task `up` (default) or `down` |
| `delete_task` | Delete a task |
| `get_task_checklist` | List checklist items on a task |
| `add_checklist_item` | Add a checklist item |
| `update_checklist_item` | Edit text/completed on a checklist item |
| `score_checklist_item` | Toggle checklist item complete |
| `delete_checklist_item` | Remove a checklist item |
| `get_tags` / `create_tag` | Tag CRUD (subset) |
| `get_inventory` / `get_pets` / `get_mounts` | Inventory views |
| `feed_pet` / `hatch_pet` / `equip_item` | Pet & gear actions |
| `buy_reward` / `get_shop` / `buy_item` | Reward purchases |
| `cast_spell` | Cast a class spell on self / a task / a party member |
| `get_notifications` / `read_notification` | Notification handling |
| `run_cron` | Trigger the daily cron manually |

## Differences from upstream

- **Single dependency** — only `@modelcontextprotocol/sdk`. axios, zod and the i18n layer are gone.
- **English-only** output messages.
- **`x-client` header** sent so Habitica can attribute traffic back to the MCP.
- **Better errors** — surfaces the Habitica API's `message` field instead of swallowing it.
- **Structured success messages** — score_task returns the gold/exp/level deltas, create_task returns the new id, etc.
- Adds `get_task` and `run_cron`; minor schema cleanups (priority enum, completedTodos filter).

## License

MIT — same as upstream.