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

Related MCP server: YNAB MCP Server

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

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.