Skip to main content
Glama
xunji-private-mcp

xunji-private-mcp

by Vdk1639

xunji-private-mcp

使用训记官方 API 的私人 MCP 服务,支持 Windows、Linux 及 Docker,提供 stdio 和 Streamable HTTP 两种连接方式。

模块

能力

服务器环境变量

训练

读取和写回训练记录,查询官方训练计划

XUNJI_TRAIN_KEY

饮食

读取和写回饮食记录,维护自定义食物

XUNJI_FOOD_KEY

食物搜索

搜索训记官方食物

XUNJI_FOOD_SEARCH_KEY

身体指标

按日期和指标读取和写入记录

XUNJI_BODY_KEY

Agent 个人模板

同步、维护专属文件夹中的训练模板

XUNJI_AGENT_TEMPLATE_KEY

写入需要客户端支持 MCP 表单确认。客户端无法展示确认时,可以使用查询工具。饮食模板查询和套用等待官方请求字段公开。

Windows 和 Linux

克隆本仓库并在仓库目录执行以下命令。uv 会在需要时安装 Python 3.12。

uv sync --locked --no-dev --python 3.12
Copy-Item .env.example .env

Linux 使用 cp .env.example .env,可用 chmod 600 .env 限制文件权限。编辑 .env,按需填入从训记 App 获取的 Key。设置的进程环境变量优先于 .env。服务默认从当前目录读取 .env,也可用全局参数 --env-file 或 XUNJI_ENV_FILE 指定绝对路径。

  • 客户端以子进程启动 stdio。配置命令为 uv --directory "<仓库绝对路径>" run --locked --no-dev xunji-private-mcp stdio。

  • 单独启动本机 HTTP 服务时,执行 uv run --locked --no-dev xunji-private-mcp http。在客户端使用 http://127.0.0.1:8765/mcp。

  • 使用 GitHub Releases 下载的 wheel 时,执行 uv tool install --python 3.12 ./xunji_private_mcp-0.1.0-py3-none-any.whl。替换为实际文件名后,可通过 xunji-private-mcp --env-file "<.env 绝对路径>" stdio 或对应的 http 子命令启动。

Related MCP server: Garmin Connect MCP Server

Docker

在 Linux Docker 或 Windows Docker Desktop 的 Linux 容器模式下,在仓库目录配置 .env,然后运行:

docker compose up -d --build

GitHub 发布后也可使用对应版本的预构建镜像,将 <owner> 替换为小写的 GitHub 仓库所有者。

docker run -d --name xunji-private-mcp --env-file .env -p 127.0.0.1:8765:8765 --read-only --cap-drop ALL --security-opt no-new-privileges ghcr.io/<owner>/xunji-private-mcp:v0.1.0

本机 HTTP 地址为 http://127.0.0.1:8765/mcp。服务器检查 Host 和 Origin,端口上的其他本机进程也能访问 MCP。仅在可信的单用户环境中启用 HTTP。跨主机访问可使用 SSH 将远端回环端口转发到本机,并限制 SSH 账户的访问权限。

ssh -N -L 127.0.0.1:8765:127.0.0.1:8765 user@server.example.com

客户端配置

以下示例中的 <仓库绝对路径> 请替换为本机路径。图形客户端找不到 uv 时,可将 command 替换为 uv 的绝对路径。已安装 wheel 的用户可改用 xunji-private-mcp 命令及 --env-file。

Codex

在 ~/.codex/config.toml 中添加 stdio 配置。若要用 HTTP,则只保留 url = "http://127.0.0.1:8765/mcp" 与 tool_timeout_sec,并提前启动 HTTP 服务。写入时在客户端弹出的 MCP 表单里审核变更。

[mcp_servers.xunji-private-mcp]
command = "uv"
args = ["--directory", "<仓库绝对路径>", "run", "--locked", "--no-dev", "xunji-private-mcp", "stdio"]
tool_timeout_sec = 180

VS Code

用 MCP: Open User Configuration 打开用户级 MCP 配置。HTTP 连接示例如下。使用 stdio 时可把 type 改为 stdio,并将 url 换成与上例相同的 command 和 args。

{
  "servers": {
    "xunji-private-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Claude Code

任选一种连接,HTTP 方式需要先启动服务。

claude mcp add --scope user --transport stdio xunji-private-mcp -- uv --directory "<仓库绝对路径>" run --locked --no-dev xunji-private-mcp stdio
claude mcp add --scope user --transport http xunji-private-mcp http://127.0.0.1:8765/mcp

密钥轮换与故障处理

  • 在训记 App 获取新 Key 后更新对应的环境变量或 .env 项。原生部署重启 MCP 进程,Compose 运行 docker compose up -d --force-recreate,docker run 部署重建容器。轮换无需改源码或重新构建镜像。

  • 缺少或失效的 Key 只影响对应工具。失效提示出现时核对 App 中的授权及会员状态。如遇限频,按工具给出的等待时间再试。

  • 真实 Key 和含 Key 的训记附件请保存在本机。.env.example 可提交,.env 不应提交。HTTP MCP 复用服务器所配的训记账户。

开发与发布

uv sync --locked --python 3.12 安装测试依赖,uv run pytest 运行离线测试。GitHub Actions 在 Windows 和 Linux 验证 wheel 的 stdio 接入,并在 Linux 验证 Compose 的 HTTP 接入。

发布时将与 pyproject.toml 版本一致的 v* 标签推送到 GitHub。发布流程上传 wheel 到 GitHub Releases,并将 linux/amd64 和 linux/arm64 镜像推送到 GHCR。首发后在 GitHub Packages 为该镜像设置公开可见性,使用户可匿名拉取。

本项目采用 MIT 许可。

Available Tools

12 tools
get_official_planB
Read-only

Read the days for a listed plan_ref. Omit dates for the default range or supply a range of at most 92 days.

Inputs: plan_ref (required), end_date, start_date, include_movements.

get_trainingB
Read-only

Get training for one day. Use full data for heart rate, rest times, RPE and unfinished sets.

Inputs: datestr (required), include_full_data.

list_official_plansA
Read-only

List official PlatformPlan and UniversalPlan instances and their plan_ref values.

Inputs: no named parameters.

mutate_agent_templatesA
DestructiveIdempotent

Apply confirmed changes to the single Agent folder.

First sync the templates. To create, pass stable client_id, name, and public movements with official Chinese names. To update, pass template_id, its base_version, and changed name/color/movements or native movement/rules. Specified movement lists replace the entire list. A delete uses template_id and base_version. To rename the folder, pass folder_update with name and the folder's current base_version. Reuse mutation_id for the same change. A new template is allowed to recreate a missing Agent folder.

Inputs: mutation_id (required), deletes, upserts, folder_update.

query_body_metricsB
Read-only

Read personal Xunji body metric records. Omit types to include all metrics.

Use the wire name weist for waist circumference. Use limit and offset to paginate records.

Inputs: end_date (required), start_date (required), limit, types, +3 more.

query_food_recordsC
Read-only

Read the requested inclusive date range of Xunji food records.

Inputs: end_date (required), start_date (required), include_detail.

search_official_foodB
Read-only

Search Xunji's official foods. Prefer foods over the compact d array in the result.

Each d row is [id, name, cal, carb, fat, protein, foodpic, uniquekey, units]. Nutrition values are per 100 g. Preserve uniquekey, ntr and units when recording a match.

Inputs: keyword (required), limit.

sync_agent_templatesA
Read-only

Fetch all Agent-folder templates and current versions. This never creates a folder.

Inputs: no named parameters.

upsert_body_metricsA
DestructiveIdempotent

Preview and confirm adding or updating body metrics by date and type.

Use kg for weight, % for bodyfat, and cm for circumference or size. Reuse client_request_id if retrying the same request after an uncertain result.

Inputs: records (required), client_request_id.

upsert_custom_foodA
Destructive

Save a custom food after user confirmation. Use a custom food when official search has no suitable match or the user requests one. For updates, supply its existing uniquekey.

Provide a real nutrition source and known kcal, protein, fat and carbohydrate per 100 g. The source is shown to the user. Omit portion units for gram-based tracking. Use food from the result when recording that food.

Inputs: ntr (required), name (required), nutrition_source (required), units, +2 more.

upsert_food_recordsA
Destructive

Add or update food records after user confirmation. Supply the record id for updates.

Obtain uniquekey, per-100g ntr and any units from official search or the saved custom food. Ask the user to resolve uncertain food matches, meal types, amounts or units. Reuse client_request_id if retrying the same request after an uncertain result.

Inputs: foods (required), client_request_id.

upsert_trainingA
DestructiveIdempotent

Create or patch up to four same-day trainings, after the user's confirmation.

Provide datestr and movements for new records. Use localid for updates and include only changed fields. If movements are supplied for an update they replace the entire list, including unfinished sets. Use verified Chinese movement names and reuse client_request_id when retrying the same write.

Inputs: trains (required), client_request_id (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 12 tools

    Disambiguation4/5

    The four food tools are distinguishable by lifecycle stage (catalog search vs. record read vs. record write vs. custom-food creation), and the training/plan/body-metric/template tools each target a distinct resource. The main risk is the shared `upsert_*` verb family across four unrelated domains and the search vs. query split for food reads, which an agent could momentarily confuse.

    Naming Consistency4/5

    All twelve names are snake_case verb_noun (search_official_food, upsert_training, list_official_plans, query_body_metrics), so the pattern is predictable. Minor deviation: read operations use three different verbs (search, query, get, list), which slightly weakens predictability but remains readable.

    Tool Count5/5

    Twelve tools is squarely in the well-scoped range and each tool maps to a concrete resource-action pair (six read, six write). No tool looks redundant or like filler.

    Completeness4/5

    Coverage spans the full domain: food search/records/custom foods, body metrics, trainings, official plans, and agent templates, with read and write in every mutable area. Minor gaps exist — there is no explicit delete for food records or body metrics (only upsert), and plans are read-only, though that may be intentional.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables reading Fitbod training history, generating workouts via Fitbod's engine, configuring workout programs, and tracking body composition over time.
      4
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Enables authorized clients to search and read titles, people, feeds, reviews, and account data for a single configured account, and to perform permitted writes such as managing watchlists, custom lists, reviews, comments, posts, and profile settings over local stdio or authenticated HTTP.
      89
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables clients to read diary entries, nutrients, water, exercise, measurements, goals, recipes, and saved meals; search foods and serving sizes; estimate nutrition and edible weight from images; and make explicitly requested diary/account updates with idempotency and read-back safeguards. Supports local stdio connections and an OAuth-secured HTTPS gateway with separate read/write grants and local approval for sensitive operations.
      -