Skip to main content
Glama

habitca-mcp

Un pequeño servidor del Protocolo de Contexto de Modelos (MCP) que expone la API v3 de Habitica como herramientas MCP, para que los asistentes de IA compatibles con MCP (Claude Code, Hermes Agent, Cursor, etc.) puedan leer y actualizar tus tareas, hábitos, diarias, recompensas, mascotas, inventario y notificaciones de Habitica.

Esta es una reescritura limpia del original de iBreaker: misma superficie, sin axios/zod/i18n, Node de archivo único, salida solo en inglés.

Instalación

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

Se requiere Node 18 o superior (utiliza fetch integrado).

Related MCP server: Habitica MCP

Autenticación

Necesitas tus credenciales de la API de Habitica:

  1. Abre https://habitica.com/user/settings/api

  2. Copia tu ID de usuario y tu Token de API

Expórtalos en la terminal que lanzará el servidor:

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

Opcional:

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

Ejecución

npm start
# or
./index.js

El servidor habla MCP a través de stdio. Registra habitca-mcp ready en stderr una vez conectado.

Conectar a un cliente MCP

Claude Code / Hermes Agent / Cursor

Añádelo a la configuración MCP del cliente:

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

Específicamente para Hermes:

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

Herramientas

Herramienta

Propósito

get_user_profile

Documento completo del usuario

get_stats

HP / MP / XP / nivel / oro / clase

get_tasks

Listar tareas (opcionalmente filtrar por habits / dailys / todos / rewards / completedTodos)

get_task

Obtener una tarea por id

create_task

Crear hábito/diaria/todo/recompensa

update_task

Actualizar los campos de una tarea

score_task

Puntuar una tarea up (por defecto) o down

delete_task

Eliminar una tarea

get_task_checklist

Listar elementos de la lista de verificación de una tarea

add_checklist_item

Añadir un elemento a la lista de verificación

update_checklist_item

Editar texto/completado en un elemento de la lista de verificación

score_checklist_item

Alternar el estado completado de un elemento de la lista de verificación

delete_checklist_item

Eliminar un elemento de la lista de verificación

get_tags / create_tag

CRUD de etiquetas (subconjunto)

get_inventory / get_pets / get_mounts

Vistas de inventario

feed_pet / hatch_pet / equip_item

Acciones de mascotas y equipo

buy_reward / get_shop / buy_item

Compras de recompensas

cast_spell

Lanzar un hechizo de clase sobre ti mismo / una tarea / un miembro del grupo

get_notifications / read_notification

Gestión de notificaciones

run_cron

Ejecutar el cron diario manualmente

Diferencias con la versión original

  • Dependencia única — solo @modelcontextprotocol/sdk. axios, zod y la capa i18n han sido eliminados.

  • Salida solo en inglés.

  • Cabecera x-client enviada para que Habitica pueda atribuir el tráfico al MCP.

  • Mejores errores — muestra el campo message de la API de Habitica en lugar de ocultarlo.

  • Mensajes de éxito estructurados — score_task devuelve los deltas de oro/exp/nivel, create_task devuelve el nuevo id, etc.

  • Añade get_task y run_cron; limpiezas menores de esquema (enum de prioridad, filtro completedTodos).

Licencia

MIT — igual que la versión original.

Available Tools

28 tools
add_checklist_itemC

Add a checklist item to a task.

Inputs: taskId (required), text (required).

buy_itemC

Buy an item from a shop.

Inputs: itemKey (required), quantity.

buy_rewardC

Buy a custom reward by key.

Inputs: key (required).

cast_spellB

Cast a class spell, optionally on a target task or party member.

Inputs: spellId (required), targetId.

create_tagD

Create a tag.

Inputs: name (required).

create_taskB

Create a habit, daily, todo, or reward.

Inputs: type (required), text (required), notes, difficulty, +4 more.

delete_checklist_itemC

Delete a checklist item.

Inputs: taskId (required), itemId (required).

delete_taskC

Delete a task by id.

Inputs: taskId (required).

equip_itemC

Equip a pet, mount, costume piece, or battle gear.

Inputs: type (required), key (required).

feed_petB

Feed a pet a piece of food.

Inputs: pet (required), food (required).

get_inventoryA

Get full inventory (items, eggs, food, hatching potions, special).

Inputs: no named parameters.

get_mountsA

Get owned mounts map.

Inputs: no named parameters.

get_notificationsC

Get unread notifications.

Inputs: no named parameters.

get_petsA

Get owned pets map.

Inputs: no named parameters.

get_shopB

Get items in a shop (default: market).

Inputs: shopType.

get_statsA

Get user stats only (HP, MP, XP, level, gold, class).

Inputs: no named parameters.

get_tagsA

Get all tags.

Inputs: no named parameters.

get_taskC

Get a single task by id.

Inputs: taskId (required).

get_task_checklistC

Get checklist items for a task.

Inputs: taskId (required).

get_tasksC

List tasks. Optionally filter by type.

Inputs: type.

get_user_profileA

Get the authenticated user's full profile (stats, prefs, items, party, etc).

Inputs: no named parameters.

hatch_petC

Hatch a pet from an egg + hatching potion.

Inputs: egg (required), hatchingPotion (required).

read_notificationC

Mark a notification as read.

Inputs: notificationId (required).

run_cronA

Run the daily cron (advance day, apply damage from missed dailies). Normally auto-runs on first action of the day.

Inputs: no named parameters.

score_checklist_itemC

Toggle a checklist item complete/incomplete.

Inputs: taskId (required), itemId (required).

score_taskA

Score a task. direction='up' completes a todo/daily or marks a + habit; 'down' is for negative habits.

Inputs: taskId (required), direction.

update_checklist_itemB

Update text/completed on a checklist item.

Inputs: taskId (required), itemId (required), text, completed.

update_taskC

Update fields on a task (text, notes, difficulty, priority, etc).

Inputs: taskId (required), text, notes, difficulty, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 28 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    28 tools cover a broad gamification system (tasks, inventory, pets, spells, shop). Slightly high but justified by the feature set; not excessive.

    Completeness3/5

    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.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Enables AI assistants to interact with the Habitica API to manage tasks, track habits, and engage in gamified productivity features like pet raising and inventory management. It allows users to control their Habitica account through natural language for a personalized and automated productivity experience.
      26
      20 npm
      26
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for managing Habitica as a daily execution layer, enabling agents to read and (with explicit confirmation) create, complete, and score tasks via the Habitica API.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP-compatible clients to read and write a gamified self-improvement RPG character sheet, including quest management, profile viewing, skills, social challenges, and leaderboards.
      1
      MIT