habitca-mcp
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 installSe requiere Node 18 o superior (utiliza fetch integrado).
Related MCP server: Habitica MCP
Autenticación
Necesitas tus credenciales de la API de Habitica:
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 analyticsEjecución
npm start
# or
./index.jsEl 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.jsHerramientas
Herramienta | Propósito |
| Documento completo del usuario |
| HP / MP / XP / nivel / oro / clase |
| Listar tareas (opcionalmente filtrar por |
| Obtener una tarea por id |
| Crear hábito/diaria/todo/recompensa |
| Actualizar los campos de una tarea |
| Puntuar una tarea |
| Eliminar una tarea |
| Listar elementos de la lista de verificación de una tarea |
| Añadir un elemento a la lista de verificación |
| Editar texto/completado en un elemento de la lista de verificación |
| Alternar el estado completado de un elemento de la lista de verificación |
| Eliminar un elemento de la lista de verificación |
| CRUD de etiquetas (subconjunto) |
| Vistas de inventario |
| Acciones de mascotas y equipo |
| Compras de recompensas |
| Lanzar un hechizo de clase sobre ti mismo / una tarea / un miembro del grupo |
| Gestión de notificaciones |
| 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-clientenviada para que Habitica pueda atribuir el tráfico al MCP.Mejores errores — muestra el campo
messagede 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_taskyrun_cron; limpiezas menores de esquema (enum de prioridad, filtro completedTodos).
Licencia
MIT — igual que la versión original.
Available Tools
28 toolsadd_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
Scored across 28 tools
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.
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.
28 tools cover a broad gamification system (tasks, inventory, pets, spells, shop). Slightly high but justified by the feature set; not excessive.
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
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
AgentReady Tools is a searchable catalog of more than 250 APIs, MCP servers and developer tools that AI agents can use, each with agent-readiness checks (docs, auth, OpenAPI, MCP support). Search by task, get tool details and related tools, and read or share field notes from other agents in the Agent Community. Remote MCP endpoint: https://agentready-tools.com/mcp
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables 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.2620 npm26MIT
- AlicenseNot gradedqualityCmaintenanceMCP 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
- AlicenseNot gradedqualityDmaintenanceEnables MCP-compatible clients to read and write a gamified self-improvement RPG character sheet, including quest management, profile viewing, skills, social challenges, and leaderboards.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables managing tasks, tags, and user stats on a self-hosted Habitica instance through MCP tools over Streamable HTTP.MIT