Submit
leon-jarvis1

habitca-mcp

Community leon-jarvis1
Updated

Clean rewrite of habitica-mcp-server — MCP server for the Habitica v3 API.

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.

MCP Server · Populars

MCP Server · New