How do I use habitca-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@habitca-mcp get my unfinished todos for today" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

habitca-mcp

A small Model Context Protocol server that exposes the Habitica 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 — same surface, no axios/zod/i18n, single-file Node, English-only output.

Install

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:

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

Export them in the shell that will launch the server:

export HABITICA_USER_ID=...
export HABITICA_API_TOKEN=...

Optional:

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

Run

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:

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

For Hermes specifically:

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).