habitca-mcp

Ein kleiner Model Context Protocol-Server, der die Habitica v3 API als MCP-Tools bereitstellt, damit MCP-fähige KI-Assistenten (Claude Code, Hermes Agent, Cursor usw.) deine Habitica-Aufgaben, Gewohnheiten, Tagesaufgaben, Belohnungen, Haustiere, Inventar und Benachrichtigungen lesen und aktualisieren können.

Dies ist eine saubere Neufassung des Originals von iBreaker — gleiche Oberfläche, kein axios/zod/i18n, Single-File Node, nur englische Ausgabe.

Installation

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

Node 18 oder neuer ist erforderlich (verwendet das integrierte fetch).

Authentifizierung

Du benötigst deine Habitica API-Zugangsdaten:

Öffne https://habitica.com/user/settings/api
Kopiere deine User ID und dein API Token

Exportiere sie in der Shell, die den Server startet:

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

Optional:

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

Ausführen

npm start
# or
./index.js

Der Server spricht MCP über stdio. Er protokolliert habitca-mcp ready in stderr, sobald die Verbindung hergestellt ist.

In einen MCP-Client einbinden

Claude Code / Hermes Agent / Cursor

Füge dies zur MCP-Konfiguration des Clients hinzu:

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

Speziell für Hermes:

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

Tools

Tool	Zweck
`get_user_profile`	Vollständiges Benutzerdokument
`get_stats`	HP / MP / XP / Level / Gold / Klasse
`get_tasks`	Aufgaben auflisten (optional filtern nach `habits` / `dailys` / `todos` / `rewards` / `completedTodos`)
`get_task`	Eine Aufgabe anhand der ID abrufen
`create_task`	Gewohnheit/Tagesaufgabe/Todo/Belohnung erstellen
`update_task`	Felder einer Aufgabe aktualisieren
`score_task`	Eine Aufgabe `up` (Standard) oder `down` bewerten
`delete_task`	Eine Aufgabe löschen
`get_task_checklist`	Checklisten-Elemente einer Aufgabe auflisten
`add_checklist_item`	Ein Checklisten-Element hinzufügen
`update_checklist_item`	Text/Status eines Checklisten-Elements bearbeiten
`score_checklist_item`	Checklisten-Element als erledigt markieren
`delete_checklist_item`	Ein Checklisten-Element entfernen
`get_tags` / `create_tag`	Tag-CRUD (Teilmenge)
`get_inventory` / `get_pets` / `get_mounts`	Inventar-Ansichten
`feed_pet` / `hatch_pet` / `equip_item`	Haustier- & Ausrüstungsaktionen
`buy_reward` / `get_shop` / `buy_item`	Belohnungskäufe
`cast_spell`	Einen Klassenzauber auf sich selbst / eine Aufgabe / ein Gruppenmitglied wirken
`get_notifications` / `read_notification`	Benachrichtigungsverwaltung
`run_cron`	Den täglichen Cron manuell auslösen

Unterschiede zum Original

Einzelne Abhängigkeit — nur @modelcontextprotocol/sdk. axios, zod und die i18n-Schicht wurden entfernt.
Nur englische Ausgabemeldungen.
x-client Header wird gesendet, damit Habitica den Datenverkehr dem MCP zuordnen kann.
Bessere Fehlerbehandlung — zeigt das message-Feld der Habitica API an, anstatt es zu unterdrücken.
Strukturierte Erfolgsmeldungen — score_task gibt die Gold/Exp/Level-Deltas zurück, create_task gibt die neue ID zurück, etc.
Fügt get_task und run_cron hinzu; kleinere Schema-Bereinigungen (Prioritäts-Enum, completedTodos-Filter).