habitca-mcp

一个小型模型上下文协议 (MCP) 服务器，将 Habitica v3 API 作为 MCP 工具公开，以便支持 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 凭据：

1. 打开 https://habitica.com/user/settings/api

2. 复制您的 User ID 和 API Token

在启动服务器的 shell 中导出它们：

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 协议通信。连接成功后，它会将 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。

• 更好的错误处理 — 直接显示 Habitica API 的 message 字段，而不是将其吞掉。

• 结构化的成功消息 — score_task 返回金币/经验/等级的变化量，create_task 返回新 ID 等。

• 添加了 get_task 和 run_cron；进行了微小的模式清理（优先级枚举，completedTodos 过滤器）。

许可证

MIT — 与上游相同。