Habitica MCP Server

中文文档请阅读

A Model Context Protocol (MCP) server that lets AI assistants seamlessly interact with the Habitica API – create tasks, track habits, raise pets and enjoy gamified productivity.

✨ Features

🎮 Core Gameplay Features

• 📋 Smart task management – create / view / update / delete all task types

• ✅ Checklist management – add, update, delete and score checklist items within tasks

• 🎯 Habit tracking – record habit completions and build healthy routines

• 🐾 Pet raising – hatch and feed pets, watch them grow

• 🏇 Mount collection – manage and equip all kinds of mounts

• 🛍️ Shop & rewards – browse and buy in-game items

• ⚡ Skill system – cast class skills to enhance gameplay

📊 Data-oriented Features

• 👤 User profile – fetch detailed user information and stats

• 🏷️ Tag management – create and manage tags for better organisation

• 📬 Notification centre – read and manage system notifications

• 📦 Inventory – list every item and piece of equipment you own

🤖 AI Integration Highlights

• 🧠 Natural-language control – operate Habitica via conversation

• 📝 Task suggestions – AI can create tasks on demand

• 📈 Progress reporting – automatically track and summarise progress

• 🎨 Personalised experience – tailored recommendations based on your habits

🚀 Quick Start

Prerequisites

• Node.js 18+

• npm or yarn

• A valid Habitica account

Installation

1. Clone the repo

2. Install dependencies

3. Set API credentials (see next section)

4. Start the server

⚙️ Configuration

Get Habitica API credentials

1. Log into Habitica

2. Click your avatar → Settings

3. Open the API tab

4. Copy User ID and API Token

Environment variables

Method A: export variables

Method B: .env file

⚠️ Security tip: never commit your API keys to version control.

🎯 Usage

Start the server

MCP client integration

The server follows the MCP spec and works with any AI client that supports MCP. Example Claude Desktop config:

Example dialogue

🛠️ Available Tools

User Related

• get_user_profile: Get user profile information

• get_stats: Get user statistics

• get_inventory: Get inventory list

Task Management

• get_tasks: Get task list (can specify type: habits, dailys, todos, rewards)

• create_task: Create new task

• update_task: Update task

• delete_task: Delete task

• score_task: Complete task or record habit

Checklist Management

• get_task_checklist: Get checklist items for a task

• add_checklist_item: Add checklist item to task

• update_checklist_item: Update checklist item

• delete_checklist_item: Delete checklist item

• score_checklist_item: Score checklist item (mark complete/incomplete)

Tag Management

• get_tags: Get tag list

• create_tag: Create new tag

Pets and Mounts

• get_pets: Get pet list

• feed_pet: Feed pet

• hatch_pet: Hatch pet

• get_mounts: Get mount list

• equip_item: Equip pet, mount or equipment

Shop and Purchases

• get_shop: Get shop item list

• buy_item: Buy shop item

• buy_reward: Buy reward

Notification Management

• get_notifications: Get notification list

• read_notification: Mark notification as read

Skill System

• cast_spell: Cast spell

📖 API Usage Examples

Create Task

Complete Task

Get Specific Task Type

Pet Management

Buy Item

Checklist Management

Task Types

• habit: Habit (can be recorded positively or negatively)

• daily: Daily task (resets every day)

• todo: To-do item (one-time task)

• reward: Reward (can be purchased with gold)

Difficulty Levels

• 0.1: Easy

• 1: Medium

• 1.5: Hard

• 2: Extreme

Priority Levels

• 0.1: Low

• 1: Medium

• 1.5: High

• 2: Extreme

🔧 Troubleshooting

Common Issues

Issue: Server startup failed

Issue: API call failed

Issue: Task or pet not found

Debug Mode

Get Help

• 📚 Check Habitica API Documentation

• 🐛 Submit Issues

🤝 Contributing

We welcome all forms of contributions!

How to Contribute

1. Fork this project

2. Create feature branch (git checkout -b feature/AmazingFeature)

3. Commit changes (git commit -m 'Add some AmazingFeature')

4. Push to branch (git push origin feature/AmazingFeature)

5. Create Pull Request

Development Guidelines

• Follow existing code style

• Add appropriate tests

• Update relevant documentation

• Ensure all tests pass

📄 License

This project is open source under the MIT License - see the LICENSE file for details.

🌟 Acknowledgments

• Thanks to Habitica for providing an excellent API

• Thanks to Anthropic for the MCP protocol

• Thanks to all contributors and users for their support