Habitica MCP Server

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

1. Clone the repo

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

2. Install dependencies

npm install

3. Set API credentials (see next section)

4. Start the server

npm start

⚙️ 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

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 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

{
  "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 Tas