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:

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:

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

License

MIT — same as upstream.