Skip to content
Back to search

habitica-mcp

Remote MCP Server for Habitica REST API v3 on Cloudflare Workers (Streamable HTTP)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kurokirasama--habitica-mcp/badge.svg)](/listings/kurokirasama--habitica-mcp)

HTML

<a href="/listings/kurokirasama--habitica-mcp"><img src="/api/listings/kurokirasama--habitica-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 49 lines
  1. # habitica-mcp
  2. A lightweight, self-hosted Remote Model Context Protocol (MCP) server for the **Habitica REST API v3**, built with TypeScript and deployed on **Cloudflare Workers** over **Streamable HTTP** (`/mcp`).
  3. > **Status:** Initial repository bootstrap — implementation in progress.
  4. ## Overview
  5. `habitica-mcp` connects MCP-compatible AI clients (such as Gemini Web Custom Apps) directly to `https://habitica.com/api/v3` without third-party aggregator middleware. It provides compact, LLM-friendly JSON payloads, strict input validation with `zod`, outbound request timeouts, and Habitica rate-limit (`HTTP 429` / `Retry-After`) handling.
  6. ## Planned MCP Tools
  7. 1. `habitica_list_tasks` — List pending or completed tasks by category (`GET /api/v3/tasks/user`)
  8. 2. `habitica_create_task` — Create a new todo, daily, habit, or reward (`POST /api/v3/tasks/user`)
  9. 3. `habitica_score_task` — Complete a todo/daily or score a habit (`POST /api/v3/tasks/{taskId}/score/{direction}`)
  10. 4. `habitica_update_task` — Edit title, notes, due date, priority, or tags (`PUT /api/v3/tasks/{taskId}`)
  11. 5. `habitica_delete_task` — Permanently delete a task (`DELETE /api/v3/tasks/{taskId}`)
  12. 6. `habitica_manage_checklist` — Add or toggle checklist items (`POST /api/v3/tasks/{taskId}/checklist` & `.../score`)
  13. 7. `habitica_get_user_stats` — Fetch character HP, MP, XP, GP, level, and quest status (`GET /api/v3/user`)
  14. 8. `habitica_list_tags` — Retrieve user tags (`GET /api/v3/tags`)
  15. 9. `habitica_cast_skill` — Cast a class skill with pre-execution MP safety check (`POST /api/v3/user/class/cast/{spellId}`)
  16. ## Configuration & Secrets
  17. Worker secrets (stored via Wrangler, never committed):
  18. - `HABITICA_USER_ID` — Habitica User ID (UUID)
  19. - `HABITICA_API_TOKEN` — Habitica API Token (UUID)
  20. - `MCP_AUTH_TOKEN` — 256-bit Bearer token protecting `POST /mcp`
  21. ## Development & Deployment (Planned)
  22. ```bash
  23. # Local development (configure secrets in .dev.vars)
  24. npx wrangler dev
  25. # Upload production secrets
  26. npx wrangler secret put HABITICA_USER_ID
  27. npx wrangler secret put HABITICA_API_TOKEN
  28. npx wrangler secret put MCP_AUTH_TOKEN
  29. # Deploy to Cloudflare Workers
  30. npx wrangler deploy
  31. ```
  32. ## Endpoints
  33. - `GET /health` — Unauthenticated liveness check (`200 OK`)
  34. - `POST /mcp` — Authenticated Streamable HTTP MCP JSON-RPC endpoint

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.