habitica

This MCP server enables AI assistants to control and interact with Habitica via natural-language commands and the MCP (Model Context Protocol). It exposes a range of actions across user data, tasks, habits, pets, mounts, inventory, shop items, and notifications, allowing you to create, view, update, and manage Habitica resources through structured MCP calls. You can query your profile and stats, manage tasks and checklists, track habit progress, hatch and feed pets, and manage mounts, shop purchases, and notifications. The server also supports task suggestions, progress reporting, and personalized recommendations based on your habits. To use it, connect an MCP-compatible client and supply your Habitica credentials (User ID and API Token) via environment variables. Example clients can reference the provided MCP config snippet to initialize the connection with the proper environment variables and language preference (MCP_LANG).

With the included tools, you can perform actions such as get_user_profile, get_tasks (with type filters like habits, dailys, todos, rewards), create_task, update_task, delete_task, score_task, and similarly manage checklists, tags, pets, mounts, shop interactions, and notifications. You can also cast spells via the skill system and obtain progress updates. The MCP client can issue natural-language prompts or structured JSON requests, and the server will translate them into Habitica API calls, returning structured responses that your AI can interpret and present to users.

Prerequisites:

• Node.js 18+ installed on your machine
• npm (or yarn) installed
• A Habitica account with API credentials (User ID and API Token)

Installation steps:

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Create or update your environment variables:

• Option A: export variables (shell):

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

• Option B: create a .env file (recommended for local development):

HABITICA_USER_ID=your-user-id
HABITICA_API_TOKEN=your-api-token

4. Start the server:

npm start

5. Optional: Development with auto-reload:

npm run dev

6. If using MCP with an external client, ensure MCP_LANG is set to your preferred language, e.g., en or zh-CN.

Tips and troubleshooting:

• Keep your Habitica API credentials secure; do not commit them to version control.
• Ensure Node.js version is 18+ for compatibility with the server.
• If API calls fail, verify your User ID and API Token are correct and that your Habitica account has the necessary permissions.
• For development, use the DEV script to enable verbose logging (DEBUG=* npm start) to help diagnose issues.
• When deploying, consider using a environment management method (e.g., .env files or container environment variables) to avoid exposure of credentials.
• The MCP_LANG setting controls the language of prompts and responses; set it to en or zh-CN as needed.
• The server follows the MCP specification; any MCP-compliant client should work by providing the mcpServers configuration snippet.