Elite MCP

一个 MCP（模型上下文协议）服务器，为 AI 代理提供对自托管 Elite 实例的直接、实时读写访问——这是一个用于记录训练、饮食、有氧运动和体重的个人健身追踪器。

如果你是一个正在阅读本文以决定如何使用此服务器的代理：在调用任何工具之前，请通读整个文件。 它涵盖了每个工具的功能、其参数的含义、预期的单位/格式，以及容易出错的地方（主要是：写入是即时且真实的，没有撤销功能）。下面的“数据模型说明”和“安全说明”部分与工具列表本身同样重要。

这是什么，以及它不是什么

Elite（该应用）将所有数据存储在自己的 SQLite 数据库中，背后是一个简单的 REST API——没有本地缓存，没有离线队列，只有一个事实来源。这个 MCP 服务器是该 API 之上的一个轻量协议适配器：这里的每次工具调用都是向你所指向的特定、已在运行的 Elite 实例发起的一个（或两个）HTTP 请求。它自身不保存任何状态，也不做任何缓存——连续调用两次 get_workout_history，你会得到两次全新的读取结果。

它不是一个通用的健身 API，它不与其他任何应用通信，也不做食物数据库查询（没有 OpenFoodFacts/USDA 搜索）——该查询逻辑位于 Elite Web 应用本身的客户端，不通过 HTTP 暴露。如果你需要记录一个不在该用户现有数据中的食物，请使用 log_food，并填入你已知或用户提供的宏量营养素数据；这里没有“按名称搜索食物”的工具。

要求

• 一个正在运行的 Elite 实例，并且你知道它的 URL（例如 http://192.168.1.50:8080，或任何自托管的位置）。如果你需要搭建一个，请参阅 Elite 仓库。

• Node.js 18+。

• 如果该 Elite 实例在启动时设置了 API_TOKEN，你将需要相同的令牌。

设置

git clone https://github.com/natyavidhan/elite-mcp.git
cd elite-mcp
npm install
cp .env.example .env   # then fill in ELITE_BASE_URL (and ELITE_API_TOKEN if the server needs one)

这是一个标准的 stdio MCP 服务器——它旨在由 MCP 客户端自己的配置来启动，而不是独立运行并保持开启。将你的代理/客户端指向 node /path/to/elite-mcp/index.js，并将 ELITE_BASE_URL（以及可选的 ELITE_API_TOKEN）作为环境变量传入。对于读取 JSON 配置的客户端（Claude Desktop、Claude Code 以及大多数其他客户端都遵循这种形式）：

{
  "mcpServers": {
    "elite": {
      "command": "node",
      "args": ["/path/to/elite-mcp/index.js"],
      "env": {
        "ELITE_BASE_URL": "http://192.168.1.50:8080",
        "ELITE_API_TOKEN": ""
      }
    }
  }
}

对于没有 JSON 配置 MCP 客户端的代理运行时（例如自定义编排器），同样的两个环境变量加上通过 stdio 启动 node index.js 就是全部约定——参见 index.js 和 src/client.js，两者都很简短。

如果未设置 ELITE_BASE_URL，进程会向 stderr 记录一条错误并立即退出，而不是以损坏的状态启动。

工具

共 20 个工具：1 个连接检查工具、11 个只读分析工具、1 个查询工具和 7 个写入工具。每个工具都以 JSON 文本块的形式返回结果；失败（Elite 不可达、令牌错误、404、验证错误）会以正常的工具结果返回，带有 isError: true 和 {"error": "..."} 主体——它不会使 MCP 连接崩溃，所以请检查这一点，而不是假定成功。

连接

• check_connection — 无参数。访问 Elite 的 /api/health。如果其他任何操作失败，请先调用此工具；它会告诉你服务器是否可达，以及其 AI Coach 是否已启用（与本 MCP 服务器无关，但这是一个有用的信号，表明你正在与正确的实例通信）。

分析（只读）

这些工具与 Elite 内置 AI Coach 在内部调用的内容完全一致——相同的函数、相同的计算方式，因此这里的数字始终与用户在应用中看到的一致。

• get_workout_history({ days? }) — 最近 N 天（默认 30 天）的训练会话：日期、动作、组数、总训练量。

• get_exercise_trend({ exerciseName, limit? }) — 单个动作随时间变化的每次会话最佳重量，以及其历史最佳纪录（PR）。exerciseName 采用模糊匹配（精确 id、精确名称或子字符串）——你不需要先调用 list_exercises 就能读取趋势。

• get_personal_records({ limit? }) — 每个动作的最佳重量和最佳单组训练量，按重量从高到低排列。

• get_muscle_volume({ date }) — 某一天的逐肌肉训练量（主动肌按全额计算，协同肌按半额计算）。

• get_weekly_muscle_summary({ days? }) — 最近 N 天（默认 7 天）内每块肌肉的总训练量，按排名排列——用这个来找出哪些肌肉训练不足。

• get_muscle_exercise_split({ muscle, days? }) — 哪些动作构成了某块肌肉的训练量，以及各自所占的比例（例如“我的肱三头肌构成是怎样的”）。muscle 必须是下面列出的枚举值之一。

• get_food_log({ date }) — 某一天记录的所有饮食条目，包含宏量营养素，以及当天的总计。

• get_nutrition_trend({ days? }) — 最近 N 天（默认 7 天）的每日卡路里/宏量营养素总计，以及用户配置的每日目标。

• get_cardio_summary({ days? }) — 最近 N 天（默认 30 天）的有氧运动会话，以及个人最佳纪录。

• get_body_weight_trend({ days? }) — 最近 N 天（默认 90 天）的体重记录，以及当前/起始/变化/7 天平均值。

• get_consistency({ days? }) — 最近 N 天（默认 14 天）内，用户每天是否记录了训练、饮食、有氧运动和体重。

查询

• list_exercises({ query? }) — 完整的动作目录（内置动作 + 该实例的自定义动作），可选地按 id 或名称的不区分大小写的子字符串匹配进行过滤。如果你还不知道确切的 exerciseId，请在调用 log_workout_set 之前先调用此工具——目录使用特定的 id，如 barbell_bench_press，而不是自由文本，log_workout_set 会拒绝任何不是真实 id 的内容。

写入

这里的每次写入都会立即生效于正在运行的 Elite 实例——在对某人的真实数据使用这些工具之前，请先阅读下面的安全说明。

• log_workout_set({ date, exerciseId, reps, weightKg, rpe? }) — 记录一组训练。如果当天的训练会话尚不存在，会自动创建。返回创建的组以及 isPR: true/false。rpe（主观疲劳评分，1–10）为可选参数。

• delete_workout_set({ setId }) — 删除一组已记录的训练。

• delete_workout_session({ sessionId }) — 删除整个训练会话及其下的所有组。没有确认步骤——此工具会完全按照其描述执行。

• log_food({ date, mealType, name, quantityG, calories, protein?, carbs?, fat? }) — 记录一条饮食条目。宏量营养素是 quantityG 的总量，而不是每 100 克的值（此工具会为你完成换算）。会在后台创建一个 manual 来源的食物条目。

• delete_food_log({ logId }) — 删除一条已记录的饮食条目。

• log_cardio_session({ date, activityType, durationSeconds, distanceKm?, avgHeartRate?, caloriesBurned?, notes? }) — 记录一次有氧运动会话。

• log_body_weight({ date, weightKg, bodyFatPct?, notes? }) — 按日期进行更新或插入（upsert）：对已有条目的日期再次记录会覆盖原条目，而不是创建重复条目。这是有意为之（Elite 应用本身就是这样行为的），不是 bug。

数据模型说明

• 日期始终是 YYYY-MM-DD 字符串，没有时间部分，没有时区。此服务器上没有“今天”辅助函数——如果用户说“把这个记录为今天的”，请在调用工具之前自行解析出今天的日期。

• ID（sessionId、setId、logId、exerciseId 等）是由 Elite 服务器生成的不透明字符串（对于动作，则在其目录中定义）——绝不要自行构造或猜测。请从先前工具的结果中获取（log_workout_set 的响应会给你真实的 set.id 和 sessionId），或从 list_exercises 获取。

• muscle 枚举（用于 get_muscle_exercise_split）：chest、triceps、shoulder、lats、bicep、forearm、traps、quads、hamstrings、glutes、calves、abs。

• mealType：breakfast、lunch、dinner、snack。

• activityType：run、walk、cycle、swim、other。

• 重量单位是千克，距离单位是千米，时长单位是秒——始终如此，无论用户将 Elite 界面设置为显示哪种单位制。

安全说明

• 没有撤销功能。 delete_workout_set、delete_workout_session 和 delete_food_log 是对用户真实训练/营养历史的真实、即时删除。不要试探性地调用删除工具，也不要“只是为了看看会发生什么”——除非用户明确要求删除，否则请先与用户确认。

• log_body_weight 会静默覆盖该日期的现有条目，而不是报错或询问——如果你不确定用户是否已经记录了今天的体重，请先调用 get_body_weight_trend。

• 此服务器除了单一的共享 ELITE_API_TOKEN（如果目标实例使用的话）之外不做任何授权——它的访问权限完全等同于该令牌所授予的权限，而默认情况下该权限是全部权限。请相应地对待它。

仓库结构

index.js         entry point — starts the stdio MCP server
src/client.js     fetch wrapper around the target Elite instance's REST API
src/tools.js      every tool's schema + implementation

相关链接

• natyavidhan/elite — 追踪器本身。其 README 记录了此服务器所基于的完整 REST API（/api/data/*、/api/workout/*、/api/analytics/* 等），如果你需要此 MCP 服务器尚未作为工具暴露的功能。