habitca-mcp

Небольшой сервер протокола Model Context Protocol, который предоставляет API Habitica v3 в качестве инструментов MCP, чтобы ИИ-ассистенты с поддержкой MCP (Claude Code, Hermes Agent, Cursor и др.) могли читать и обновлять ваши задачи, привычки, ежедневные задания, награды, питомцев, инвентарь и уведомления в Habitica.

Это чистая переработка оригинала от iBreaker — тот же интерфейс, без axios/zod/i18n, один файл Node, вывод только на английском языке.

Установка

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

Требуется Node 18 или новее (используется встроенный fetch).

Авторизация

Вам понадобятся ваши учетные данные API Habitica:

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

Сервер общается по протоколу MCP через stdio. После подключения он записывает habitca-mcp ready в stderr.

Подключение к 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.

• Улучшенная обработка ошибок — выводит поле message API Habitica вместо его подавления.

• Структурированные сообщения об успехе — score_task возвращает дельту золота/опыта/уровня, create_task возвращает новый id и т.д.

• Добавлены get_task и run_cron; небольшие исправления схемы (enum приоритета, фильтр completedTodos).

Лицензия

MIT — такая же, как в оригинале.