habitica-simple-mcp

Use Habitica from Claude on your phone. No local install, deploys in about 2 minutes.

A single-file MCP server for Habitica, written as a dependency-free Cloudflare Worker. Everything lives in worker.js: paste it into the Cloudflare dashboard and you have a remote MCP server for Claude (or any MCP client that supports remote HTTP servers).

Tools

Task responses are slimmed down to the useful fields, since the raw Habitica task object is very large.

Related MCP server: Capacities MCP Worker

Setup

1. Click the Deploy to Cloudflare button above (it will ask for the three secrets in step 2), or in the Cloudflare dashboard go to Workers & Pages → Create → Create Worker, then Edit code and paste in the contents of worker.js. Deploy.

2. Under Settings → Variables and Secrets add three secrets:

   Name	Value
   HABITICA_USER_ID	Your User ID from Habitica → Settings → Site Data → API
   HABITICA_API_TOKEN	Your API token from the same page
   MCP_SECRET	A long random string (at least 24 characters), e.g. openssl rand -hex 24

   Optionally set HABITICA_API_BASE to point at a different Habitica API (defaults to https://habitica.com/api/v3).

   Temporary Habitica errors are retried inside the server (up to 3 times with backoff). 429 is always retried and honors Retry-After; 5xx and network errors are retried for everything except POST, to avoid double-scoring or duplicate creates. HABITICA_RETRY_BASE_MS (default 500) sets the base delay.

   Habitica API reference: habitica.com/apidoc (source of the doc blocks: tasks.js).

3. Your MCP endpoint is:

   https://<worker>.<subdomain>.workers.dev/mcp/<MCP_SECRET>

4. Add it to your client as a remote MCP server. With Claude Code:

   claude mcp add --transport http habitica https://<worker>.<subdomain>.workers.dev/mcp/<MCP_SECRET>

   In Claude.ai, add it as a custom connector using the same URL.

Prefer the CLI? npx wrangler deploy works too, using the included wrangler.toml, with npx wrangler secret put <NAME> for each secret.

Security

• The secret in the URL is the only authentication, so treat the full URL like a password. Anyone with it can act on your Habitica account.

• Requests with a wrong or missing secret get a 404, and secrets shorter than 24 characters are rejected outright.

• The server is stateless and only accepts POST (MCP streamable HTTP, JSON mode).

Local testing

npx wrangler dev
curl -s localhost:8787/mcp/$MCP_SECRET \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Put the three variables in a .dev.vars file (git-ignored) for local runs.

Development

npm install
npm test            # node:test suite, Habitica is mocked
npm run format      # prettier
npm run check       # syntax check

CI runs formatting, the syntax check and the tests on Node 20 and 22.

License

MIT