Habitica MCP Server

English version available at README.md.

这是一个 Model Context Protocol (MCP) 服务器，让 AI 助手能够与 Habitica API 无缝交互，帮助您管理任务、追踪习惯、养成宠物，享受游戏化的生产力提升。

✨ 功能特性

🎮 核心游戏化功能

• 📋 智能任务管理: 创建、查看、更新和删除各类任务
• ✅ 清单管理: 在任务中添加、更新、删除和完成清单项目
• 🎯 习惯追踪: 记录习惯完成情况，培养良好生活方式
• 🐾 宠物养成: 孵化、喂养宠物，享受成长乐趣
• 🏇 坐骑收集: 管理和装备各种坐骑
• 🛍️ 商店购买: 浏览和购买游戏内物品
• ⚡ 技能系统: 施放角色技能，增强游戏体验

📊 数据管理功能

• 👤 用户档案: 获取详细的用户信息和统计数据
• 🏷️ 标签管理: 创建和管理任务标签，更好地组织任务
• 📬 通知中心: 查看和管理系统通知
• 📦 物品清单: 查看拥有的所有物品和装备

🤖 AI 集成特色

• 🧠 智能对话: 通过自然语言与 AI 助手交互
• 📝 任务建议: 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. 点击右上角头像 → Settings
3. 选择 API 选项卡
4. 复制 User ID 和 API Token

设置环境变量

方法一：使用环境变量

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

方法二：创建 .env 文件

# 在项目根目录创建 .env 文件
HABITICA_USER_ID=your-user-id-here
HABITICA_API_TOKEN=your-api-token-here

⚠️ 安全提醒: 请勿将 API 凭据提交到版本控制系统中

🎯 使用方法

启动服务器

# 生产环境
npm start

# 开发环境 (支持热重载)
npm run dev

与 MCP 客户端集成

这个服务器遵循 Model Context Protocol (MCP) 标准，可以与各种支持 MCP 的 AI 客户端集成使用。

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

示例对话

用户: "帮我创建一个学习 Python 的习惯"
AI: "好的，我来为您创建一个学习 Python 的习惯任务..."

用户: "查看我今天的任务"
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": "任务ID",
  "text": "研究需求"
}

// 更新清单项目
{
  "taskId": "任务ID",
  "itemId": "清单项目ID",
  "text": "更新的项目文本",
  "completed": true
}

// 为清单项目评分（切换完成状态）
{
  "taskId": "任务ID",
  "itemId": "清单项目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 文档
• 🐛 提交 Issues

🤝 贡献指南

我们欢迎各种形式的贡献！

如何贡献

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 协议
• 感谢所有贡献者和用户的支持