Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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.
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.
git clone https://github.com/hxlair/habitca_mcp.git
cd habitca_mcp
npm installNode 18 or newer is required (uses the built-in fetch).
Related MCP server: Habitica MCP
You need your Habitica API credentials:
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 analyticsnpm start
# or
./index.jsThe server speaks MCP over stdio. It logs habitca-mcp ready to stderr once connected.
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.jsTool | Purpose |
| Full user document |
| HP / MP / XP / level / gold / class |
| List tasks (optionally filter by |
| Fetch one task by id |
| Create habit/daily/todo/reward |
| Update a task's fields |
| Score a task |
| Delete a task |
| List checklist items on a task |
| Add a checklist item |
| Edit text/completed on a checklist item |
| Toggle checklist item complete |
| Remove a checklist item |
| Tag CRUD (subset) |
| Inventory views |
| Pet & gear actions |
| Reward purchases |
| Cast a class spell on self / a task / a party member |
| Notification handling |
| Trigger the daily cron manually |
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).
MIT — same as upstream.
Add a checklist item to a task.
Inputs: taskId (required), text (required).
Buy an item from a shop.
Inputs: itemKey (required), quantity.
Buy a custom reward by key.
Inputs: key (required).
Cast a class spell, optionally on a target task or party member.
Inputs: spellId (required), targetId.
Create a tag.
Inputs: name (required).
Create a habit, daily, todo, or reward.
Inputs: type (required), text (required), notes, difficulty, +4 more.
Delete a checklist item.
Inputs: taskId (required), itemId (required).
Delete a task by id.
Inputs: taskId (required).
Equip a pet, mount, costume piece, or battle gear.
Inputs: type (required), key (required).
Feed a pet a piece of food.
Inputs: pet (required), food (required).
Get full inventory (items, eggs, food, hatching potions, special).
Inputs: no named parameters.
Get owned mounts map.
Inputs: no named parameters.
Get unread notifications.
Inputs: no named parameters.
Get owned pets map.
Inputs: no named parameters.
Get items in a shop (default: market).
Inputs: shopType.
Get user stats only (HP, MP, XP, level, gold, class).
Inputs: no named parameters.
Get all tags.
Inputs: no named parameters.
Get a single task by id.
Inputs: taskId (required).
Get checklist items for a task.
Inputs: taskId (required).
List tasks. Optionally filter by type.
Inputs: type.
Get the authenticated user's full profile (stats, prefs, items, party, etc).
Inputs: no named parameters.
Hatch a pet from an egg + hatching potion.
Inputs: egg (required), hatchingPotion (required).
Mark a notification as read.
Inputs: notificationId (required).
Run the daily cron (advance day, apply damage from missed dailies). Normally auto-runs on first action of the day.
Inputs: no named parameters.
Toggle a checklist item complete/incomplete.
Inputs: taskId (required), itemId (required).
Score a task. direction='up' completes a todo/daily or marks a + habit; 'down' is for negative habits.
Inputs: taskId (required), direction.
Update text/completed on a checklist item.
Inputs: taskId (required), itemId (required), text, completed.
Update fields on a task (text, notes, difficulty, priority, etc).
Inputs: taskId (required), text, notes, difficulty, +2 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 28 tools
Most tools have clearly distinct purposes (e.g., get_task vs get_tasks, buy_item vs buy_reward). A few overlaps exist (get_inventory and get_user_profile both return items) but descriptions reduce ambiguity.
All tool names follow a consistent verb_noun snake_case pattern (e.g., create_task, buy_item, equip_item). No mixing of conventions or chaotic naming.
28 tools cover a broad gamification system (tasks, inventory, pets, spells, shop). Slightly high but justified by the feature set; not excessive.
Core task and checklist operations are complete, but missing CRUD for tags (no delete/update), rewards management beyond buying, and some inventory actions. Notable gaps exist.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
