xunji-private-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@xunji-private-mcp Log today's workout: bench press 4x8 at 80kg, then 3x12 cable flys"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
xunji-private-mcp
使用训记官方 API 的私人 MCP 服务,支持 Windows、Linux 及 Docker,提供 stdio 和 Streamable HTTP 两种连接方式。
模块 | 能力 | 服务器环境变量 |
训练 | 读取和写回训练记录,查询官方训练计划 |
|
饮食 | 读取和写回饮食记录,维护自定义食物 |
|
食物搜索 | 搜索训记官方食物 |
|
身体指标 | 按日期和指标读取和写入记录 |
|
Agent 个人模板 | 同步、维护专属文件夹中的训练模板 |
|
写入需要客户端支持 MCP 表单确认。客户端无法展示确认时,可以使用查询工具。饮食模板查询和套用等待官方请求字段公开。
Windows 和 Linux
克隆本仓库并在仓库目录执行以下命令。uv 会在需要时安装 Python 3.12。
uv sync --locked --no-dev --python 3.12
Copy-Item .env.example .envLinux 使用 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 --buildGitHub 发布后也可使用对应版本的预构建镜像,将 <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 = 180VS 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 toolsget_official_planBRead-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_trainingBRead-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_plansARead-only
List official PlatformPlan and UniversalPlan instances and their plan_ref values.
Inputs: no named parameters.
mutate_agent_templatesADestructiveIdempotent
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_metricsBRead-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_recordsCRead-only
Read the requested inclusive date range of Xunji food records.
Inputs: end_date (required), start_date (required), include_detail.
search_official_foodBRead-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_templatesARead-only
Fetch all Agent-folder templates and current versions. This never creates a folder.
Inputs: no named parameters.
upsert_body_metricsADestructiveIdempotent
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_foodADestructive
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_recordsADestructive
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_trainingADestructiveIdempotent
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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
Read your workouts, history, and stats; create and schedule new workouts. Writes are additive only.
Access COROS activity, training and health data, and manage training plans and workouts.
Agent-first strength-training platform across iOS, Web & MCP: read & write workouts, PRs & plans.
Connect Claude, Cursor or any MCP client to your GymUp training data.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables reading Fitbod training history, generating workouts via Fitbod's engine, configuring workout programs, and tracking body composition over time.4MIT
- AlicenseNot gradedqualityCmaintenanceEnables read-only access to Garmin Connect health, activity, profile, and device data through local stdio or streamable HTTP transports for MCP clients.MIT
- AlicenseCqualityCmaintenanceEnables 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.89MIT
- FlicenseNot gradedqualityBmaintenanceEnables 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.-