Back to search
habitica-mcp
MCP serverGitHub
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
Markdown
[](/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
- # habitica-mcp
- 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`).
- > **Status:** Initial repository bootstrap — implementation in progress.
- ## Overview
- `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.
- ## Planned MCP Tools
- 1. `habitica_list_tasks` — List pending or completed tasks by category (`GET /api/v3/tasks/user`)
- 2. `habitica_create_task` — Create a new todo, daily, habit, or reward (`POST /api/v3/tasks/user`)
- 3. `habitica_score_task` — Complete a todo/daily or score a habit (`POST /api/v3/tasks/{taskId}/score/{direction}`)
- 4. `habitica_update_task` — Edit title, notes, due date, priority, or tags (`PUT /api/v3/tasks/{taskId}`)
- 5. `habitica_delete_task` — Permanently delete a task (`DELETE /api/v3/tasks/{taskId}`)
- 6. `habitica_manage_checklist` — Add or toggle checklist items (`POST /api/v3/tasks/{taskId}/checklist` & `.../score`)
- 7. `habitica_get_user_stats` — Fetch character HP, MP, XP, GP, level, and quest status (`GET /api/v3/user`)
- 8. `habitica_list_tags` — Retrieve user tags (`GET /api/v3/tags`)
- 9. `habitica_cast_skill` — Cast a class skill with pre-execution MP safety check (`POST /api/v3/user/class/cast/{spellId}`)
- ## Configuration & Secrets
- Worker secrets (stored via Wrangler, never committed):
- - `HABITICA_USER_ID` — Habitica User ID (UUID)
- - `HABITICA_API_TOKEN` — Habitica API Token (UUID)
- - `MCP_AUTH_TOKEN` — 256-bit Bearer token protecting `POST /mcp`
- ## Development & Deployment (Planned)
- ```bash
- # Local development (configure secrets in .dev.vars)
- npx wrangler dev
- # Upload production secrets
- npx wrangler secret put HABITICA_USER_ID
- npx wrangler secret put HABITICA_API_TOKEN
- npx wrangler secret put MCP_AUTH_TOKEN
- # Deploy to Cloudflare Workers
- npx wrangler deploy
- ```
- ## Endpoints
- - `GET /health` — Unauthenticated liveness check (`200 OK`)
- - `POST /mcp` — Authenticated Streamable HTTP MCP JSON-RPC endpoint
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.