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-clientheader sent so Habitica can attribute traffic back to the MCP.- Better errors — surfaces the Habitica API's
messagefield instead of swallowing it. - Structured success messages — score_task returns the gold/exp/level deltas, create_task returns the new id, etc.
- Adds
get_taskandrun_cron; minor schema cleanups (priority enum, completedTodos filter).
License
MIT — same as upstream.