习惯ica-MCP服务器

Name: 习惯ica-MCP服务器
Author: iBreaker

作者：iBreaker7 星标更新：2025-07-09

安装使用来源：spider==github.com

项目介绍

Habitica MCP 服务器

✨ 特性

🎮 核心游戏功能

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

📊 数据导向功能

👤 用户资料 – 获取详细的用户信息和统计数据
🏷️ 标签管理 – 创建和管理标签以更好地组织内容
📬 通知中心 – 阅读和管理系统通知
📦 库存 – 列出您拥有的每一件物品和装备

🤖 AI 集成亮点

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

🚀 快速开始

先决条件

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

安装

克隆仓库

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

安装依赖

npm install

设置 API 凭证（见下一节）
启动服务器

npm start

⚙️ 配置

获取 Habitica API 凭证

登录 Habitica
点击您的头像 → 设置
打开 API 标签页
复制 用户ID 和 API 密钥

环境变量

方法 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 密钥提交到版本控制系统。

🎯 使用

启动服务器

# 生产环境
npm start

# 开发环境（带自动重载）
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"  // 或者 zh-CN
      }
    }
  }
}

示例对话

用户: "创建一个学习 Python 的习惯"
AI:   "好的，习惯已创建！"

用户: "显示我今天的任务"
AI:   "这是您今天要完成的任务列表……"

用户: "在我的项目任务中添加一个检查清单项：'审查代码'"
AI:   "已在您的项目任务中添加了检查清单项 '审查代码'！"

用户: "我完成了我的锻炼，请记录一下"
AI:   "做得好！锻炼已记录。"

🛠️ 可用工具

用户相关

get_user_profile: 获取用户资料信息
get_stats: 获取用户统计数据
get_inventory: 获取库存列表

任务管理

get_tasks: 获取任务列表（可指定类型：habits, dailys, todos, rewards）
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": "完成项目文档",
  "notes": "包括 API 文档和用户指南",
  "difficulty": 1.5,
  "priority": 2,
  "checklist": [
    {"text": "编写 API 文档", "completed": false},
    {"text": "创建用户指南", "completed": false},
    {"text": "审阅和校对", "completed": false}
  ]
}

完成任务

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

获取特定任务类型

{
  "type": "todos"
}

宠物管理

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

购买物品

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

检查清单管理

// 添加检查清单项
{
  "taskId": "task-id-here",
  "text": "研究需求"
}

// 更新检查清单项
{
  "taskId": "task-id-here",
  "itemId": "checklist-item-id",
  "text": "更新项目文本",
  "completed": true
}

// 评分检查清单项（切换完成状态）
{
  "taskId": "task-id-here",
  "itemId": "checklist-item-id"
}

任务类型

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

难度等级

0.1: 简单
1: 中等
1.5: 困难
2: 极难

优先级等级

0.1: 低
1: 中等
1.5: 高
2: 极高

🔧 故障排除

常见问题

问题：服务器启动失败

解决方案: 
1. 检查 Node.js 版本是否为 18+
2. 确认环境变量设置正确
3. 验证 API 凭证有效

问题：API 调用失败

解决方案:
1. 检查网络连接
2. 验证 Habitica API 凭证
3. 确认未超过 API 请求频率限制

问题：任务或宠物未找到

解决方案:
1. 确认任务 ID 正确
2. 检查任务是否存在于 Habitica
3. 验证用户权限

调试模式

# 启用详细日志
DEBUG=* npm start

获取帮助

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

🤝 贡献

我们欢迎任何形式的贡献！

如何贡献

分叉此项目
创建功能分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
创建拉取请求

开发指南

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

📄 许可证

本项目在 MIT 许可证下开源 - 详情请参阅 LICENSE 文件。

🌟 致谢

感谢 Habitica 提供优秀的 API
感谢 Anthropic 提供 MCP 协议
感谢所有贡献者和用户的大力支持

<div align="center"> <b>让 AI 成为您 Habitica 任务管理助手吧！</b> </div>