habitca-mcp

Habitica v3 APIをMCPツールとして公開する小さなModel Context Protocolサーバーです。これにより、MCP対応のAIアシスタント（Claude Code、Hermes Agent、Cursorなど）がHabiticaのタスク、習慣、デイリー、報酬、ペット、インベントリ、通知を読み取り、更新できるようになります。

これはiBreakerによるオリジナル版をクリーンに書き直したものです。インターフェースは同じですが、axios/zod/i18nを使用せず、単一ファイルのNode.jsで構成され、出力は英語のみです。

インストール

git clone https://github.com/hxlair/habitca_mcp.git
cd habitca_mcp
npm install

Node 18以降が必要です（組み込みの fetch を使用するため）。

認証

HabiticaのAPI認証情報が必要です：

1. https://habitica.com/user/settings/api を開きます

2. User ID と API Token をコピーします

サーバーを起動するシェルでこれらをエクスポートします：

export HABITICA_USER_ID=...
export HABITICA_API_TOKEN=...

オプション：

export HABITICA_APP_ID=my-mcp-client      # sent as x-client header for Habitica analytics

実行

npm start
# or
./index.js

サーバーはstdio経由でMCPと通信します。接続が確立されると、stderrに habitca-mcp ready とログが出力されます。

MCPクライアントへの接続

Claude Code / Hermes Agent / Cursor

クライアントのMCP設定に追加します：

{
  "mcpServers": {
    "habitca": {
      "command": "node",
      "args": ["/absolute/path/to/habitca_mcp/index.js"],
      "env": {
        "HABITICA_USER_ID": "...",
        "HABITICA_API_TOKEN": "..."
      }
    }
  }
}

Hermesの場合：

hermes mcp add habitca \
  --env HABITICA_USER_ID=... \
  --env HABITICA_API_TOKEN=... \
  -- node /absolute/path/to/habitca_mcp/index.js

ツール

上流版との違い

• 単一の依存関係 — @modelcontextprotocol/sdk のみ。axios、zod、i18nレイヤーは削除されました。

• 英語のみ の出力メッセージ。

• x-client ヘッダー を送信し、HabiticaがMCPからのトラフィックを識別できるようにしました。

• より優れたエラー処理 — Habitica APIの message フィールドを隠さず表示します。

• 構造化された成功メッセージ — score_task はゴールド/経験値/レベルの変動を返し、create_task は新しいIDを返すなど。

• get_task と run_cron を追加。スキーマの軽微な整理（優先度enum、completedTodosフィルター）。

ライセンス

MIT — 上流版と同じです。