Habitica MCP Server
中文文档请阅读 README.zh-CN.md
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
- Clone the repo
git clone https://github.com/ibreaker/habitica-mcp-server.git
cd habitica-mcp-server
- Install dependencies
npm install
-
Set API credentials (see next section)
-
Start the server
npm start
⚙️ Configuration
Get Habitica API credentials
- Log into Habitica
- Click your avatar → Settings
- Open the API tab
- Copy User ID and API Token
Environment variables
Method A: export variables
export HABITICA_USER_ID="your-user-id"
export HABITICA_API_TOKEN="your-api-token"
Method B: .env file
HABITICA_USER_ID=your-user-id
HABITICA_API_TOKEN=your-api-token
⚠️ Security tip: never commit your API keys to version control.
🎯 Usage
Start the server
# Production
npm start
# Development (with reload)
npm run dev
MCP client integration
The server follows the MCP spec and works with any AI client that supports MCP. Example Claude Desktop config:
{
"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
}
}
}
}
Example dialogue
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."
🛠️ Available Tools
User Related
get_user_profile: Get user profile informationget_stats: Get user statisticsget_inventory: Get inventory list
Task Management
get_tasks: Get task list (can specify type: habits, dailys, todos, rewards)create_task: Create new taskupdate_task: Update taskdelete_task: Delete taskscore_task: Complete task or record habit
Checklist Management
get_task_checklist: Get checklist items for a taskadd_checklist_item: Add checklist item to taskupdate_checklist_item: Update checklist itemdelete_checklist_item: Delete checklist itemscore_checklist_item: Score checklist item (mark complete/incomplete)
Tag Management
get_tags: Get tag listcreate_tag: Create new tag
Pets and Mounts
get_pets: Get pet listfeed_pet: Feed pethatch_pet: Hatch petget_mounts: Get mount listequip_item: Equip pet, mount or equipment
Shop and Purchases
get_shop: Get shop item listbuy_item: Buy shop itembuy_reward: Buy reward
Notification Management
get_notifications: Get notification listread_notification: Mark notification as read
Skill System
cast_spell: Cast spell
📖 API Usage Examples
Create Task
{
"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}
]
}
Complete Task
{
"taskId": "task-id-here",
"direction": "up"
}
Get Specific Task Type
{
"type": "todos"
}
Pet Management
{
"pet": "Wolf-Base",
"food": "Meat"
}
Buy Item
{
"itemKey": "armor_warrior_1",
"quantity": 1
}
Checklist Management
// 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"
}
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: Easy1: Medium1.5: Hard2: Extreme
Priority Levels
0.1: Low1: Medium1.5: High2: Extreme
🔧 Troubleshooting
Common Issues
Issue: Server startup failed
Solution:
1. Check Node.js version is 18+
2. Confirm environment variables are set correctly
3. Verify API credentials are valid
Issue: API call failed
Solution:
1. Check network connection
2. Verify Habitica API credentials
3. Confirm API rate limits haven't been exceeded
Issue: Task or pet not found
Solution:
1. Confirm task ID is correct
2. Check if task exists in Habitica
3. Verify user permissions
Debug Mode
# Enable verbose logging
DEBUG=* npm start
Get Help
- 📚 Check Habitica API Documentation
- 🐛 Submit Issues
🤝 Contributing
We welcome all forms of contributions!
How to Contribute
- Fork this project
- Create feature branch (
git checkout -b feature/AmazingFeature) - Commit changes (
git commit -m 'Add some AmazingFeature') - Push to branch (
git push origin feature/AmazingFeature) - 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
Let AI become your Habitica task management assistant!