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

Autenticación

Necesitas tus credenciales de la API de Habitica:

Abre https://habitica.com/user/settings/api
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).