Habitica Mcp Server

Habitica MCP 服务

中文文档请阅读 README.zh-CN.md

一个模型上下文协议（MCP）服务，可让 AI 助手无缝调用 Habitica API——创建任务、追踪习惯、饲养宠物，享受游戏化效率体验。

✨ 功能

🎮 核心游戏功能

• 📋 智能任务管理 – 创建 / 查看 / 更新 / 删除所有类型的任务
• ✅ 清单管理 – 在任务中添加、更新、删除清单项目并为其评分
• 🎯 习惯追踪 – 记录习惯完成情况并养成健康习惯
• 🐾 宠物饲养 – 孵化并喂养宠物，看着它们成长
• 🏇 坐骑收集 – 管理并装备各种坐骑
• 🛍️ 商店与奖励 – 浏览并购买游戏内物品
• ⚡ 技能系统 – 施放职业技能，提升游戏体验

📊 数据相关功能

• 👤 用户资料 – 获取详细的用户信息和统计数据
• 🏷️ 标签管理 – 创建和管理标签，方便整理
• 📬 通知中心 – 阅读和管理系统通知
• 📦 物品栏 – 列出你拥有的所有物品和装备

🤖 AI 集成亮点

• 🧠 自然语言控制 – 通过对话操作 Habitica
• 📝 任务建议 – AI 可按需创建任务
• 📈 进度报告 – 自动追踪并总结进度
• 🎨 个性化体验 – 根据你的习惯提供定制建议

🚀 快速开始

前置条件

• Node.js 18+
• npm 或 yarn
• 有效的 Habitica 账号

安装

1. 克隆仓库

git clone https://github.com/ibreaker/habitica-mcp-server.git
cd habitica-mcp-server

2. 安装依赖

npm install

3. 设置 API 凭据（请参阅下一节）

4. 启动服务

npm start

⚙️ 配置

获取 Habitica API 凭据

1. 登录 Habitica
2. 点击你的头像 → 设置
3. 打开 API 标签页
4. 复制 用户 ID 和 API Token

环境变量

方法 A：导出变量

export HABITICA_USER_ID="your-user-id"
export HABITICA_API_TOKEN="your-api-token"

方法 B：.env 文件

HABITICA_USER_ID=your-user-id
HABITICA_API_TOKEN=your-api-token

⚠️ 安全提示： 切勿将 API 密钥提交到版本控制系统。

🎯 使用方法

启动服务

# Production
npm start

# Development (with reload)
npm run dev

MCP 客户端集成

此服务遵循 MCP 规范，可与任何支持 MCP 的 AI 客户端配合使用。Claude Desktop 配置示例：

{
  "mcpServers": {
    "habitica-mcp-server": {
      "command": "npx",
      "args": ["-y", "habitica-mcp-server"],
      "env": {
        "HABITICA_USER_ID": "your-id",
        "HABITICA_API_TOKEN": "your-token",
        "MCP_LANG": "en"  // or zh-CN
      }
    }
  }
}

对话示例

User: "Create a habit for learning Python"
AI:   "Sure, the habit has been created!"

User: "Show me today's tasks"
AI:   "Here is your task list for today…"

User: "Add a checklist item to my project task: 'Review code'"
AI:   "Added checklist item 'Review code' to your project task!"

User: "I finished my workout, please record it"
AI:   "Great job! The workout is logged."

🛠️ 可用工具

用户相关

• get_user_profile：获取用户资料信息
• get_stats：获取用户统计数据
• get_inventory：获取物品栏列表

任务管理

• get_tasks：获取任务列表（可指定类型：习惯、每日任务、待办事项、奖励）
• create_task：创建新任务
• update_task：更新任务
• delete_task：删除任务
• score_task：完成任务或记录习惯

清单管理

• get_task_checklist：获取任务的清单项目
• add_checklist_item：向任务添加清单项目
• update_checklist_item：更新清单项目
• delete_checklist_item：删除清单项目
• score_checklist_item：为清单项目评分（标记为已完成 / 未完成）

标签管理

• get_tags：获取标签列表
• create_tag：创建新标签

宠物和坐骑

• get_pets：获取宠物列表
• feed_pet：喂养宠物
• hatch_pet：孵化宠物
• get_mounts：获取坐骑列表
• equip_item：装备宠物、坐骑或装备

商店和购买

• get_shop：获取商店物品列表
• buy_item：购买商店物品
• buy_reward：购买奖励

通知管理

• get_notifications：获取通知列表
• read_notification：将通知标记为已读

技能系统

• cast_spell：施放法术

📖 API 使用示例

创建任务

{
  "type": "todo",
  "text": "Complete project documentation",
  "notes": "Including API docs and user guide",
  "difficulty": 1.5,
  "priority": 2,
  "checklist": [
    {"text": "Write API documentation", "completed": false},
    {"text": "Create user guide", "completed": false},
    {"text": "Review and proofread", "completed": false}
  ]
}

完成任务

{
  "taskId": "task-id-here",
  "direction": "up"
}

获取特定类型的任务

{
  "type": "todos"
}

宠物管理

{
  "pet": "Wolf-Base",
  "food": "Meat"
}

购买物品

{
  "itemKey": "armor_warrior_1",
  "quantity": 1
}

清单管理

// Add checklist item
{
  "taskId": "task-id-here",
  "text": "Research requirements"
}

// Update checklist item
{
  "taskId": "task-id-here",
  "itemId": "checklist-item-id",
  "text": "Updated item text",
  "completed": true
}

// Score checklist item (toggle completion)
{
  "taskId": "task-id-here",
  "itemId": "checklist-item-id"
}

任务类型

• habit：习惯（可记录正向或负向行为）
• daily：每日任务（每天重置）
• todo：待办事项（一次性任务）
• reward：奖励（可使用金币购买）

难度等级

• 0.1：简单
• 1：中等
• 1.5：困难
• 2：极难

优先级

• 0.1：低
• 1：中
• 1.5：高
• 2：极高

🔧 故障排除

常见问题

问题：服务启动失败

Solution: 
1. Check Node.js version is 18+
2. Confirm environment variables are set correctly
3. Verify API credentials are valid

问题：API 调用失败

Solution:
1. Check network connection
2. Verify Habitica API credentials
3. Confirm API rate limits haven't been exceeded

问题：未找到任务或宠物

Solution:
1. Confirm task ID is correct
2. Check if task exists in Habitica
3. Verify user permissions

调试模式

# Enable verbose logging
DEBUG=* npm start

获取帮助

• 📚 查看 Habitica API 文档
• 🐛 提交问题

🤝 贡献

欢迎以各种形式参与贡献！

如何贡献

1. Fork 此项目
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送到分支（git push origin feature/AmazingFeature）
5. 创建 Pull Request

开发指南

• 遵循现有代码风格
• 添加适当的测试
• 更新相关文档
• 确保所有测试通过

📄 许可证

此项目基于 MIT 许可证开源，详情请参阅 LICENSE 文件。

🌟 致谢

• 感谢 Habitica 提供出色的 API
• 感谢 Anthropic 提供 MCP 协议
• 感谢所有贡献者和用户的支持

---