home / mcp / habitica mcp server

Habitica MCP Server

Provides a synchronized interface to Habitica data and actions via MCP for AI-enabled task management and progress tracking.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You use the Habitica MCP Server to let AI assistants interact with Habitica directly, enabling task creation, habit tracking, pet care, and other Habitica actions through natural conversations. This server exposes a standard MCP interface so your AI clients can issue commands and receive responses in a structured way, making Habitica management seamless and automated.

How to use

You connect an MCP client to the Habitica MCP Server to perform actions like creating tasks, updating checklists, recording habit completions, managing pets and mounts, and getting your user data. Use natural-language prompts or your client’s predefined intents to request operations such as creating tasks, listing today’s tasks, adding checklist items, or marking items as complete. The server processes these requests through the available tools and returns structured results that your AI assistant can present to you.

Typical usage flows include asking for a list of tasks, creating a new habit, updating a task’s details, or recording a completed activity. Your AI client should send requests aligned with the MCP tools described in the available capabilities, and interpret the responses to display task lists, statuses, and progress summaries.

How to install

Prerequisites: Node.js 18 or newer, npm or yarn, and a Habitica account.

1. Install dependencies and prepare the server environment.

2. Start the server when ready and keep your credentials secure.

Configuration and usage notes

Set your Habitica API credentials by obtaining your User ID and API Token from Habitica Settings under the API tab. You will supply these credentials to the MCP server as environment variables.

You can run the server in production mode or development mode with automatic reloads during development. The server supports an MCP client configuration to establish the connection and define environment variables for authentication and language.

Security reminders

Never commit your Habitica API credentials to version control. Use environment variables or a secure secret management approach to protect USER_ID and API_TOKEN.

Troubleshooting

If the server fails to start, verify Node.js is version 18 or newer, confirm environment variables are set, and ensure the Habitica credentials are valid. If API calls fail, check your network, credentials, and potential rate limits. If a task or pet cannot be found, confirm IDs and user permissions.

Available tools

get_user_profile

Fetch detailed user profile information including stats and settings.

get_stats

Retrieve user statistics to understand activity and progress.

get_inventory

List all items and equipment owned by the user.

get_tasks

Get the list of tasks, with optional filtering by type (habits, dailys, todos, rewards).

create_task

Create a new task with specified type and attributes.

update_task

Update details of an existing task.

delete_task

Remove a task from Habitica.

score_task

Complete a task or record a habit progression.

get_task_checklist

Retrieve checklist items for a specific task.

add_checklist_item

Add a new checklist item to a task.

update_checklist_item

Update an existing checklist item.

delete_checklist_item

Delete a checklist item from a task.

score_checklist_item

Toggle completion state of a checklist item.

get_tags

List all tags for organization.

create_tag

Create a new tag for categorization.

get_pets

List all hatchable pets and current pets.

feed_pet

Feed a pet to affect its growth or mood.

hatch_pet

Hatch a new pet from an egg.

get_mounts

List all mounts and current ownership.

equip_item

Equip a pet, mount, or equipment.

get_shop

List items available in the in-game shop.

buy_item

Purchase a shop item with in-game currency.

buy_reward

Purchase a reward using in-game currency.

get_notifications

Fetch system notifications for the user.

read_notification

Mark a notification as read.

cast_spell

Cast a class-specific spell from the skill system.