habitca-mcp

Habitica v3 API를 MCP 도구로 노출하는 소규모 Model Context Protocol 서버입니다. 이를 통해 MCP를 지원하는 AI 어시스턴트(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 사용).

인증

Habitica API 자격 증명이 필요합니다:

https://habitica.com/user/settings/api 페이지를 엽니다.
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

서버는 stdio를 통해 MCP와 통신합니다. 연결되면 stderr에 habitca-mcp ready를 기록합니다.

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

도구

도구	목적
`get_user_profile`	전체 사용자 문서
`get_stats`	HP / MP / XP / 레벨 / 골드 / 직업
`get_tasks`	할 일 목록(선택적으로 `habits` / `dailys` / `todos` / `rewards` / `completedTodos`로 필터링)
`get_task`	ID로 특정 할 일 가져오기
`create_task`	습관/일일 과제/할 일/보상 생성
`update_task`	할 일의 필드 업데이트
`score_task`	할 일 점수 매기기 `up`(기본값) 또는 `down`
`delete_task`	할 일 삭제
`get_task_checklist`	할 일의 체크리스트 항목 나열
`add_checklist_item`	체크리스트 항목 추가
`update_checklist_item`	체크리스트 항목의 텍스트/완료 여부 편집
`score_checklist_item`	체크리스트 항목 완료 토글
`delete_checklist_item`	체크리스트 항목 제거
`get_tags` / `create_tag`	태그 CRUD (일부)
`get_inventory` / `get_pets` / `get_mounts`	인벤토리 보기
`feed_pet` / `hatch_pet` / `equip_item`	펫 및 장비 작업
`buy_reward` / `get_shop` / `buy_item`	보상 구매
`cast_spell`	자신 / 할 일 / 파티원에게 직업 주문 시전
`get_notifications` / `read_notification`	알림 처리
`run_cron`	일일 cron 수동 트리거

원본과의 차이점

단일 의존성 — @modelcontextprotocol/sdk만 사용합니다. axios, zod 및 i18n 계층이 제거되었습니다.
영어 전용 출력 메시지.
x-client 헤더 전송 — Habitica가 트래픽을 MCP에서 발생한 것으로 식별할 수 있습니다.
더 나은 오류 처리 — Habitica API의 message 필드를 숨기지 않고 그대로 노출합니다.
구조화된 성공 메시지 — score_task는 골드/경험치/레벨 변화량을 반환하고, create_task는 새 ID를 반환하는 등 결과가 구조화되어 있습니다.
get_task 및 run_cron 추가; 사소한 스키마 정리(우선순위 enum, completedTodos 필터).