Skip to main content
Glama

xunji-mcp

A small, self-hosted Model Context Protocol bridge for Xunji (训记) training data. It runs on Cloudflare Workers, speaks OAuth 2.1, and exposes the operator's own training history to ChatGPT and other MCP clients as a handful of read-first tools.

It is deliberately not a fitness app, not a data warehouse, and not a multi-tenant service. Your Xunji key stays in the Worker; clients get an OAuth grant, never the key.

What it gives an agent

Tool

Purpose

xunji_capabilities

What this deployment exposes, and its limits

xunji_get_training_day

One day: movements, sets, volume, duration, optional detail

xunji_list_training_days

Per-day rows for a range (≤31 days)

xunji_movement_history

One movement across days (≤62 days)

xunji_training_stats

Sessions, sets, volume, weekday split, top movements

xunji_search_movements

Canonical Chinese movement names from the public catalog

xunji_list_plans / xunji_get_plan

Official plan schedules, read-only

xunji_upsert_training_day

Opt-in write; disabled by default

Results are compact JSON with stable fields, not raw vendor payloads. Missing training is a successful empty result. Every read reports upstream limits and cache status.

Related MCP server: Garmin Personal MCP

Why the shape is unusual

Xunji paces reads per account per calendar day: 15 seconds for the light payload, 30 seconds for include_full_data. There is no range endpoint. The bridge therefore:

  • caches normalized days per identity;

  • serializes reads through a Durable Object that reserves vendor slots;

  • returns a typed deferred result with retryAfterSeconds instead of hanging;

  • caps range tools at two uncached reads per call and reports pending dates.

Writes are deliberately conservative. Verified on 2026-11-19: the vendor's training upsert ignores dry_run, so a "preview" is a real write. This project never sends that flag, requires confirmed: true, refuses dates outside six months, and cannot delete anything (the vendor has no delete API).

Nutrition and body-data endpoints use separate vendor keys; this bridge does not expose them and does not pretend to.

Quick start (local)

npm install
cp wrangler.example.jsonc wrangler.jsonc   # edit origin + KV ids
npx wrangler types
npx wrangler kv namespace create OAUTH_KV
npx wrangler kv namespace create CACHE_KV
printf 'owner-passphrase' | npx wrangler secret put OWNER_PASSPHRASE
printf 'your-xunji-key'   | npx wrangler secret put XUNJI_API_KEY
npm run typecheck && npm test
npm run dev

wrangler dev serves http://localhost:8787/mcp; the OAuth metadata uses PUBLIC_ORIGIN, so set it to http://localhost:8787 for local client testing.

Security posture

  • OAuth 2.1 authorization code + PKCE S256, exact redirect matching, resource audience, iss, refresh rotation and revocation, via @cloudflare/workers-oauth-provider.

  • Authorization requires the operator: a Cloudflare Access JWT verified against the team JWKS plus an email allowlist, or a deployment passphrase. No identity, no grant; no "allow all" switch.

  • Single-operator by design. Cache keys are identity-scoped.

  • No raw payloads, keys or tokens in logs. /healthz returns booleans only.

  • Read-only default. Writes require WRITE_TOOLS_ENABLED=true, the xunji:write scope and explicit user confirmation.

Read SECURITY.md and docs/threat-model.md before deploying publicly.

Status

The protocol and upstream behavior are covered by unit, contract and workerd integration tests (34 at v0.1.0). On 2026-11-19 a private deployment completed the full path: OAuth through Cloudflare Access, a ChatGPT connector connection, and a live tools/call returning the expected session and movement counts. That verification is deployment-specific; see docs/acceptance.md for each criterion and how to repeat it.

License

MIT. Xunji and 训记 are trademarks of their respective owners; this project is unaffiliated.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables ChatGPT or another MCP client to query a self-hosted, email-restricted Garmin Connect running archive — latest and listed runs, lap and chart details, run comparisons, trends, recovery and training context — all served read-only from a Cloudflare Worker cache with one explicit, rate-limited manual refresh. Garmin credentials are never stored, and no tool can modify the Garmin account.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables users to connect ChatGPT or remote MCP clients to their own Garmin cloud health and activity data through a self-hosted, read-only OAuth-protected Cloudflare Worker.
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables Claude and other remote MCP clients to query your own read-only Garmin Connect data — recovery trends, sleep, HRV, Body Battery, stress, heart rate, and activities — through Garmin's official Personal API, with OAuth sign-in that works from the mobile apps as well as desktop. Deploys on Cloudflare Workers' free tier with no password sharing or scraping.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables connecting your own Garmin Connect data to Claude or another MCP client so you can ask about sleep, training, heart rate, weight, and more through read-only tools running on a Cloudflare Worker.
      1
      MIT