# Habitica — how to use (mcp.ai)

Connect your Habitica account and use 70 tools for productivity straight from your AI agent. Connect with your own API key. Habitica is an open-source task management application that gamifies productivity by turning tasks into role-playing game elements.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_habitica?ms=1787296140000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `habitica_add_challenge_task`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/habitica`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/habitica/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/habitica/add/challenge/task` — Tool to add a new task to a specified challenge. Use when you need to programmatically create a challenge task after the challenge is set up and you have its ID.
  - body: { date?: string, tags?: string[], text: string, type: string, notes?: string, everyX?: integer, priority?: number, remindAt?: string, attribute?: string, frequency?: string, challengeId: string }
- `POST https://api.mcp.ai/api/habitica/add/push/device` — Tool to register a push notification device for the authenticated user. Use when you need to enable push notifications for mobile devices or UnifiedPush clients.
  - body: { type: string, regId: string }
- `POST https://api.mcp.ai/api/habitica/add/tag/to/task` — Tool to add a tag to a task. Use when you need to categorize or label a task with an existing tag.
  - body: { tag_id: string, task_id: string }
- `POST https://api.mcp.ai/api/habitica/clone/challenge` — Tool to clone an existing challenge. Use when you need to duplicate a challenge to a different group with a new name.
  - body: { name: string, group: string, shortName: string, challengeId: string }
- `POST https://api.mcp.ai/api/habitica/create/challenge` — Tool to create a new challenge. Use when you need to start a challenge in a specific group with title, summary, and optional tasks.
  - body: { name: string, group: string, prize?: integer, tasks?: object[], leader?: string, summary: string, official?: boolean, shortName: string, description?: string }
- `POST https://api.mcp.ai/api/habitica/create/group` — Create a new Habitica party for collaborative gameplay. Use this tool to create a party where users can: - Participate in quests together - Chat with party members - Share achievements and progress **
  - body: { name: string, type: string, privacy?: string, description?: string }
- `POST https://api.mcp.ai/api/habitica/create/tag` — Tool to create a new tag. Use after determining the desired tag name.
  - body: { name: string }
- `POST https://api.mcp.ai/api/habitica/create/task` — Create a new task in Habitica. Supports four task types: - 'habit': Recurring positive/negative actions (use up/down to enable +/- buttons) - 'daily': Scheduled tasks that repeat on a schedule (config
  - body: { up?: boolean, date?: string, down?: boolean, tags?: string[], text: string, type: string, alias?: string, notes?: string, value?: number, everyX?: integer, repeat?: object, priority?: number, attribute?: string, checklist?: object[], frequency?: string, reminders?: object[], startDate?: string, daysOfMonth?: integer[], weeksOfMonth?: integer[], collapseChecklist?: boolean }
- `POST https://api.mcp.ai/api/habitica/create/webhook` — Tool to create a new webhook for taskActivity events. Use when you need real-time notifications of task creation, updates, deletion, or scoring.
  - body: { url: string, type?: string, label?: string, enabled?: boolean, options: object }
- `POST https://api.mcp.ai/api/habitica/delete/challenge` — Permanently delete a Habitica challenge. Only the challenge leader (creator) or an admin can delete a challenge. This action is irreversible - once deleted, the challenge and all associated tasks are 
  - body: { challengeId: string }
- `POST https://api.mcp.ai/api/habitica/delete/group` — Leave or delete a Habitica group (party or guild). This tool allows you to: 1. Leave a party: Pass 'party' as groupId or the party's UUID to leave your current party. 2. Leave a guild: Pass the guild'
  - body: { groupId: string }
- `POST https://api.mcp.ai/api/habitica/delete/group/chat/message` — Tool to delete a chat message from a Habitica group (party, guild, or Tavern). Use when you need to remove a specific chat message. Note that only the message author or group moderators can delete mes
  - body: { chatId: string, groupId: string, previousMsg?: string }
- `POST https://api.mcp.ai/api/habitica/delete/tag` — Tool to delete a tag for the authenticated user. Use when you need to remove an obsolete tag after confirming it’s no longer applied to any tasks.
  - body: { tagId: string }
- `POST https://api.mcp.ai/api/habitica/delete/task` — Permanently deletes a user's task (habit, daily, todo, or reward) by its ID. The task cannot be recovered after deletion. Use get_tasks to list tasks and their IDs first.
  - body: { taskId: string }
- `POST https://api.mcp.ai/api/habitica/delete/task/checklist/item` — Tool to delete a checklist item from a task. Use when you need to remove a specific checklist item from a todo or daily task.
  - body: { itemId: string, taskId: string }
- `POST https://api.mcp.ai/api/habitica/delete/user/message/by/id` — Tool to delete a message from the authenticated user's inbox by its ID. Use when you need to remove a specific message from the user's Habitica inbox.
  - body: { id: string }
- `POST https://api.mcp.ai/api/habitica/delete/user/push/device` — Tool to remove a push device registration from the authenticated user's account. Use when you need to unregister a device that should no longer receive push notifications.
  - body: { regId: string }
- `POST https://api.mcp.ai/api/habitica/equip/item` — Tool to equip or unequip gear, pets, mounts, or costume items in Habitica. Use when you need to change the user's equipped items. Equipping an already-equipped item will unequip it.
  - body: { key: string, type: string }
- `POST https://api.mcp.ai/api/habitica/export/challenge/csv` — Tool to export a Habitica challenge to CSV format. Use when you need to download challenge data as a CSV file. The CSV contains all challenge tasks and participant information.
  - body: { challengeId: string }
- `POST https://api.mcp.ai/api/habitica/get/challenge` — Tool to retrieve details of a specific challenge. Use when you have the challenge ID and need its full data.
  - body: { challengeId: string }
- `POST https://api.mcp.ai/api/habitica/get/challenge/task` — Retrieve a task by its unique ID. Works for any Habitica task type (habit, daily, todo, reward) whether it belongs to a challenge or is a personal user task. Returns full task details including type-s
  - body: { task_id: string }
- `POST https://api.mcp.ai/api/habitica/get/challenge/tasks` — Tool to get all tasks for a specified challenge. Use when you have a challenge ID and need to list its defined tasks, including challenge metadata per task.
  - body: { challengeId: string }
- `POST https://api.mcp.ai/api/habitica/get/challenges` — Tool to retrieve challenges available in a specific group (guild, party, or tavern).
  - body: { groupId: string }
- `POST https://api.mcp.ai/api/habitica/get/content` — Retrieves all Habitica game content definitions in a single request. Returns ~9MB of static game data including achievements, quests, gear, pets, mounts, eggs, hatching potions, food, backgrounds, spe
  - body: { language?: string }
- `POST https://api.mcp.ai/api/habitica/get/content/by/type` — Retrieves Habitica game content data filtered by a specific category type. Use this tool to fetch game definitions like quest details, equipment stats, pet/mount info, backgrounds, spells, or other st
  - body: { type: string, language?: string }
- `POST https://api.mcp.ai/api/habitica/get/export/history/csv` — Tool to export user tasks history in CSV format. Returns CSV data with task completions and updates over time.
- `POST https://api.mcp.ai/api/habitica/get/export/inbox/html` — Tool to export inbox data in HTML format from Habitica. Use when you need to retrieve the user's private messages and inbox content as an HTML document.
- `POST https://api.mcp.ai/api/habitica/get/export/userdata/json` — Exports the authenticated user's complete data in JSON format. Use when you need a full backup or comprehensive snapshot of all user data. Returns the raw internal data structure with all fields and n
- `POST https://api.mcp.ai/api/habitica/get/group` — Retrieves detailed information about a Habitica group (guild or party). Use 'party' as groupId to get the user's current party, or provide a specific group UUID obtained from HABITICA_GET_GROUPS.
  - body: { groupId: string }
- `POST https://api.mcp.ai/api/habitica/get/group/members` — Retrieve members of a Habitica group (guild or party). Supports pagination via lastId parameter and optional search filtering. Use 'party' as groupId to get members of the current user's party.
  - body: { limit?: integer, lastId?: string, search?: string, groupId: string, includeAllPublicFields?: boolean }
- `POST https://api.mcp.ai/api/habitica/get/groups` — Retrieves Habitica groups based on type. Use 'guilds' to get all guilds the authenticated user belongs to, 'party' to get the user's current party, or 'tavern' to get the global Tavern (the main publi
  - body: { name?: string, page?: integer, type: string, limit?: integer }
- `POST https://api.mcp.ai/api/habitica/get/groups/habitrpg` — Tool to retrieve the Habitica Tavern (habitrpg) group details. The Tavern is the main public group where all Habitica users can chat and participate in community discussions.
- `POST https://api.mcp.ai/api/habitica/get/groups/party/chat` — Tool to retrieve party chat messages from Habitica. Use when you need to fetch recent chat messages from the authenticated user's party.
- `POST https://api.mcp.ai/api/habitica/get/models/model/paths` — Retrieves all available field paths and their data types for a specified Habitica model. Use this to discover the structure and available fields for user, group, challenge, tag, or task models. Helpfu
  - body: { model: string }
- `POST https://api.mcp.ai/api/habitica/get/news` — Tool to retrieve the latest Bailey announcement from Habitica. Use when you need to check current news, events, or updates posted by Bailey.
- `POST https://api.mcp.ai/api/habitica/get/party` — Retrieves the authenticated user's party details from Habitica. Returns information about the user's current party including: - Party name, description, and member count - Party leader information - C
- `POST https://api.mcp.ai/api/habitica/get/shops/market/gear` — Tool to retrieve the available gear for purchase in the market shop. Use when you need to check what equipment is available for each character class. Returns gear organized by class: healer, wizard, r
- `POST https://api.mcp.ai/api/habitica/get/shops/time/travelers` — Tool to retrieve available items in the Time Travelers shop. Use when you need to see what quests, backgrounds, pets, or mounts can be purchased with hourglasses.
- `POST https://api.mcp.ai/api/habitica/get/status` — Tool to check Habitica API server status. Use when you need to verify if the Habitica service is operational before making other API calls.
- `POST https://api.mcp.ai/api/habitica/get/tags` — Retrieve all tags for the authenticated Habitica user. Tags are labels that can be attached to tasks for organization. Returns both user-created tags and challenge-related tags. Use this to get tag ID
- `POST https://api.mcp.ai/api/habitica/get/tasks` — Tool to retrieve all tasks for the authenticated user. Use when you need the user's current tasks list after authenticating.
  - body: { type?: string }
- `POST https://api.mcp.ai/api/habitica/get/user/challenges` — Tool to retrieve challenges the authenticated user participates in. Use when you need a paginated list of user challenges.
  - body: { page?: integer, owned?: string, member?: boolean }
- `POST https://api.mcp.ai/api/habitica/get/user/profile` — Retrieves the authenticated user's complete Habitica profile. Returns comprehensive user data including: - Stats: HP, MP, level, experience, gold, and character class - Inventory: gear, pets, mounts, 
- `POST https://api.mcp.ai/api/habitica/get/webhooks` — Retrieves all webhooks configured for the authenticated Habitica user. Returns a list of webhooks including their URLs, types, enabled status, and task activity options. Use this to check existing web
- `POST https://api.mcp.ai/api/habitica/get/world/state` — Retrieves the current state of the Habitica game world including active events, world boss status, and seasonal NPC visual themes. Use when checking for active world events, monitoring world boss prog
- `POST https://api.mcp.ai/api/habitica/invite/to/group` — Tool to invite users to a specific group. Use when you need to send invitations by user UUID, email, or username.
  - body: { uuids?: string[], emails?: string|object[], groupId: string, message?: string, usernames?: string[] }
- `POST https://api.mcp.ai/api/habitica/invite/to/quest` — Tool to invite party members to a quest. Use when you want to start a quest with a specific quest key in a group. The user must own the quest scroll to invite others.
  - body: { group_id: string, quest_key: string }
- `POST https://api.mcp.ai/api/habitica/join/challenge` — Tool to join a challenge. Use after confirming the challenge ID to participate in a specific challenge.
  - body: { challengeId: string }
- `POST https://api.mcp.ai/api/habitica/leave/challenge` — Tool to leave a Habitica challenge. Use when you need to remove yourself from a specific challenge and decide whether to keep or remove its tasks.
  - body: { keep: string, challengeId: string }
- `POST https://api.mcp.ai/api/habitica/local/login` — Tool to authenticate a user via local credentials. Use when needing an API token for subsequent Habitica requests.
  - body: { password: string, username: string }
- `POST https://api.mcp.ai/api/habitica/local/register` — Tool to register a new Habitica user via email and password. Use when creating a fresh account before authentication.
  - body: { email: string, password: string, username: string, confirmPassword: string }
- `POST https://api.mcp.ai/api/habitica/mark/group/chat/seen` — Tool to mark all chat messages as read/seen for a specific group. Use when you need to clear unread message notifications in a group chat. Requires a valid group ID ('party' for user's party, 'habitrp
  - body: { groupId: string }
- `POST https://api.mcp.ai/api/habitica/mark/notification/seen` — Tool to mark a single notification as seen in Habitica. Use this when you need to mark one specific notification as read after the user has viewed it.
  - body: { notificationId: string }
- `POST https://api.mcp.ai/api/habitica/mark/notifications/seen` — Marks specific notifications as read/seen in Habitica. Use this after getting notifications to clear unread notification badges. Requires valid notification IDs from the Get Notifications action. Retu
  - body: { notificationIds: string[] }
- `POST https://api.mcp.ai/api/habitica/move/pinned/item` — Tool to move a pinned item in the rewards column to a new position. Use when you need to reorder pinned items after sorting them.
  - body: { path: string, position: integer }
- `POST https://api.mcp.ai/api/habitica/move/task/to/position` — Move a Habitica task to a new position in the task list. Use this when you need to reorder tasks by moving a specific task to the top (position=0), bottom (position=-1), or any specific position. The 
  - body: { taskId: string, position: integer }
- `POST https://api.mcp.ai/api/habitica/post/news/tell/me/later` — Tool to dismiss the latest Bailey announcement in Habitica, allowing it to be read later. Use this when the user wants to clear the current news notification without reading it. The announcement will 
- `POST https://api.mcp.ai/api/habitica/post/user/reset` — Resets the authenticated user's account to starting state. This permanently deletes all tasks, resets character to level 1, and clears progress while retaining some items and achievements. Use with ca
- `POST https://api.mcp.ai/api/habitica/read/card` — Tool to mark a card as read in Habitica. Use when a user receives a special card (birthday, greeting, nye, thankyou, or valentine) and wants to acknowledge it. Updates user.flags.cardReceived and retu
  - body: { cardType: string }
- `POST https://api.mcp.ai/api/habitica/remove/from/party` — Removes a member from the authenticated user's party. Requirements: - You must be the party leader to remove members - You cannot remove yourself (use Leave Party instead) - The member must be current
  - body: { message?: string, memberId: string }
- `POST https://api.mcp.ai/api/habitica/score/task` — Score a Habitica task to mark it as completed or incomplete. Use this tool to: - Mark a todo as complete ('up') or incomplete ('down') - Check off a daily task ('up') or uncheck it ('down') - Record a
  - body: { taskId: string, direction: string }
- `POST https://api.mcp.ai/api/habitica/social/auth` — Tool to authenticate a user via a social provider. Use after obtaining an OAuth token or code from Facebook, Google, GitHub, or Apple.
  - body: { code?: string, service: string, id_token?: string, access_token?: string, redirect_uri?: string }
- `POST https://api.mcp.ai/api/habitica/subscribe/webhook` — Tool to enable (subscribe) an existing webhook by ID for the authenticated user. This aligns with Habitica's documented API by updating the webhook resource to ensure it is enabled. Usage: obtain the 
  - body: { webhookId: string }
- `POST https://api.mcp.ai/api/habitica/unlink/all/challenge/tasks` — Tool to unlink all tasks from a Habitica challenge. Use when you need to disconnect all tasks associated with a challenge and decide whether to keep or remove them.
  - body: { keep?: string, challengeId: string }
- `POST https://api.mcp.ai/api/habitica/update/group` — Tool to update a Habitica group (party or guild) by modifying its properties. Use when you need to change the name, description, or summary of an existing group. Only the group leader can update group
  - body: { name?: string, groupId: string, summary?: string, description?: string }
- `POST https://api.mcp.ai/api/habitica/update/tag` — Tool to update an existing tag's name. Use when you need to rename a tag after identifying its ID.
  - body: { name: string, tagId: string }
- `POST https://api.mcp.ai/api/habitica/update/task` — Update an existing task in Habitica. Use this to modify task properties like title, notes, priority, or other attributes. Only include fields you want to update - all body parameters are optional.
  - body: { tags?: string[], text?: string, notes?: string, taskId: string, priority?: number, attribute?: string, checklist?: object[] }
- `POST https://api.mcp.ai/api/habitica/update/task/checklist/item` — Tool to update a checklist item in a task. Use when you need to modify the text of a specific checklist item in a todo or daily task.
  - body: { text: string, itemId: string, taskId: string }
- `POST https://api.mcp.ai/api/habitica/update/user` — Update the authenticated user's profile, preferences, flags, and other settings in Habitica. Use dot notation for nested fields (e.g., profile.name, preferences.language). Note: Some paths are protect
  - body: { profile.name?: string, flags.newStuff?: boolean, preferences.size?: string, preferences.skin?: string, preferences.chair?: string, preferences.shirt?: string, preferences.sleep?: boolean, preferences.costume?: boolean, preferences.dayStart?: integer, preferences.language?: string, flags.warnedLowHealth?: boolean, preferences.hair.base?: integer, preferences.background?: string, preferences.hair.bangs?: integer, preferences.hair.beard?: integer, preferences.hair.color?: string, preferences.hair.flower?: integer, preferences.hair.mustache?: integer, preferences.allocationMode?: string, preferences.disableClasses?: boolean }
- `POST https://api.mcp.ai/api/habitica/validate/coupon/code` — Validate a Habitica coupon code to check if it is valid and active. Use this tool to verify coupon codes before attempting to apply them to a user account. Returns information about the coupon's valid
  - body: { code: string }

## Example prompts
- "What can I do in Habitica?"
- "Show me a summary of my Habitica account"

## More
- Page: https://mcp.ai/habitica
- Agent spec (llms.txt): https://mcp.ai/habitica/llms.txt
- Postman collection: https://mcp.ai/habitica/postman.json