开发者 · MCP v1.0.0

Run4Better MCP

把你的跑步数据接进任何 AI 助手

Run4Better 提供标准的 MCP（Model Context Protocol）远程服务。在小程序里生成一个个人访问令牌，配置到 WorkBuddy、OpenClaw、Claude Code、Cursor 等支持 MCP 的客户端，AI 就能读取你的活动记录、个人最佳、成绩预测、训练状态、恢复数据与教练周报，直接围绕你的真实数据给建议。

只读：MCP 只能查询，不能修改或删除你的任何数据
按令牌授权：令牌只对应你自己的账号，随时可在小程序吊销
不含逐秒轨迹：返回摘要、分公里段、圈次与分析指标，不返回 GPS 轨迹与逐秒心率流

三步接入

打开 Run4Better 小程序 → 我的 → AI 助手接入 → 创建令牌（给它起个名字，如「WorkBuddy」）
复制生成的令牌（形如 r4b_…，只显示一次；丢了就吊销重建）
在你的 AI 客户端里添加一个 Streamable HTTP 类型的 MCP 服务器，地址填 https://api.run4better.cn/api/mcp，请求头加 Authorization: Bearer <你的令牌>

服务端点

https://api.run4better.cn/api/mcp

客户端配置

把 <TOKEN> 替换为你在小程序里创建的令牌。

Claude Code

命令行一行添加；之后在对话里直接问「我最近的训练状态怎么样」。

claude mcp add --transport http run4better https://api.run4better.cn/api/mcp \
  --header "Authorization: Bearer <TOKEN>"

WorkBuddy

编辑 ~/.workbuddy/mcp.json（或在「自定义连接器」里粘贴），保存后重启 WorkBuddy，并把 run4better 连接器设为「信任」。

{
  "mcpServers": {
    "run4better": {
      "type": "streamableHttp",
      "url": "https://api.run4better.cn/api/mcp",
      "headers": { "Authorization": "Bearer <TOKEN>" },
      "timeout": 60000
    }
  }
}

OpenClaw

写入 OpenClaw 配置的 mcp.servers；令牌建议放环境变量而非明文。

{
  "mcp": {
    "servers": {
      "run4better": {
        "url": "https://api.run4better.cn/api/mcp",
        "transport": "streamable-http",
        "headers": { "Authorization": "Bearer <TOKEN>" }
      }
    }
  }
}

Cursor

项目或全局的 .cursor/mcp.json。

{
  "mcpServers": {
    "run4better": {
      "url": "https://api.run4better.cn/api/mcp",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}

Claude Desktop / 其它仅支持 stdio 的客户端

通过 mcp-remote 桥接（需要 Node.js）。

{
  "mcpServers": {
    "run4better": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.run4better.cn/api/mcp",
               "--header", "Authorization: Bearer <TOKEN>"]
    }
  }
}

Tool 参考

共 10 个只读 tool。单位约定：时间 = 秒，距离 = 米，配速 = 秒/公里；缺失值为 null。

`get_profile`用户档案

当前用户的基础档案与累计统计：昵称、性别、年龄、心率设置、当前 VDOT、已连接数据源、累计/本周/本月跑量。

参数

无

返回字段（18）

字段	类型	说明
`nickname`	`string \| null`	昵称
`gender`	`string \| null`	性别：MALE / FEMALE
`age`	`number \| null`	年龄（岁）
`weightKg`	`number \| null`	体重（公斤）
`restingHeartRate`	`number \| null`	静息心率（bpm，训练设置）
`maxHeartRate`	`number \| null`	最大心率（bpm，训练设置）
`currentVdot`	`number \| null`	当前 VDOT（训练配速基准）
`primarySource`	`string \| null`	主数据源（多设备去重时以此为准）
`connectedSources`	`string[]`	已连接的数据源
`stats`	`object`
`stats.totalActivities`	`number`	累计活动次数（跑步类）
`stats.totalDistanceMeters`	`number`	累计距离（米）
`stats.totalDurationSec`	`number`	累计时长（秒）
`stats.thisWeekDistanceMeters`	`number`	本周距离（米）
`stats.thisMonthDistanceMeters`	`number`	本月距离（米）
`stats.totalHalfMarathons`	`number`	半马完成次数（含以上距离不重复计）
`stats.totalMarathons`	`number`	全马完成次数
`stats.currentStreakDays`	`number`	当前连续运动天数

`list_activities`活动列表

按时间倒序分页列出用户的运动记录摘要（默认最近 30 天，跨度最多 366 天，每页最多 50 条）。只含摘要指标，不含轨迹；详情用 get_activity。

参数

名称	类型	必填	默认	说明
`from`	`string`	否	—	起始日期 YYYY-MM-DD（含，北京时间日界），默认 to 往前 30 天
`to`	`string`	否	—	结束日期 YYYY-MM-DD（含，北京时间日界），默认今天
`type`	`"RUN" \| "WALK" \| "CYCLE" \| "HIKE" \| "SWIM" \| "STRENGTH" \| "CARDIO" \| "PILATES" \| "OTHER"`	否	—	活动类型过滤，默认不限
`page`	`integer`	否	`1`	页码，从 1 开始
`pageSize`	`integer`	否	`20`	每页条数，最多 50

返回字段（27）

字段	类型	说明
`items`	`object[]`
`items[].id`	`string`	活动 ID（用于 get_activity）
`items[].name`	`string \| null`	活动名称
`items[].type`	`string`	活动类型：RUN / WALK / CYCLE / HIKE / SWIM / STRENGTH / CARDIO / PILATES / OTHER
`items[].workoutType`	`string \| null`	训练类型（AI 推断）：easy / long / tempo / interval / race 等
`items[].startTime`	`string`	开始时间（RFC 3339，带活动当地时区偏移，如 2026-08-23T06:30:00+08:00）
`items[].date`	`string`	活动当地日期 YYYY-MM-DD（展示「哪天跑的」用这个）
`items[].durationSec`	`number`	时长（秒）
`items[].distanceMeters`	`number`	距离（米）
`items[].avgPaceSecPerKm`	`number \| null`	平均配速（秒/公里）
`items[].avgHeartRate`	`number \| null`	平均心率（bpm）
`items[].maxHeartRate`	`number \| null`	最大心率（bpm）
`items[].avgCadence`	`number \| null`	平均步频（spm）
`items[].elevationGainMeters`	`number \| null`	累计爬升（米）
`items[].calories`	`number \| null`	热量（kcal）
`items[].runScore`	`number \| null`	单跑综合评分 0–100（平台算法）
`items[].trainingLoad`	`number \| null`	训练负荷 TRIMP（Banister，平台算法）
`items[].isRace`	`boolean`	是否比赛（匹配到赛事库）
`items[].raceName`	`string \| null`	赛事名称
`items[].location`	`string \| null`	地点（城市/POI）
`items[].deviceName`	`string \| null`	记录设备
`items[].source`	`string`	数据来源：GARMIN / COROS / SUUNTO / ZEPP / KEEP 等
`total`	`number`	区间内总条数
`page`	`number`
`pageSize`	`number`
`from`	`string`	实际生效的起始日期
`to`	`string`	实际生效的结束日期

`get_activity`活动详情

单条运动记录的分析详情：摘要指标 + 每公里分段 + 圈次（间歇结构）+ 心率/配速区间分布 + 前后半程 + 跑步动态 + 最佳段 + 成就。不含逐秒轨迹。

参数

名称	类型	必填	默认	说明
`activityId`	`string`	是	—	活动 ID（来自 list_activities）

返回字段（84）

字段	类型	说明
`id`	`string`	活动 ID（用于 get_activity）
`name`	`string \| null`	活动名称
`type`	`string`	活动类型：RUN / WALK / CYCLE / HIKE / SWIM / STRENGTH / CARDIO / PILATES / OTHER
`workoutType`	`string \| null`	训练类型（AI 推断）：easy / long / tempo / interval / race 等
`startTime`	`string`	开始时间（RFC 3339，带活动当地时区偏移，如 2026-08-23T06:30:00+08:00）
`date`	`string`	活动当地日期 YYYY-MM-DD（展示「哪天跑的」用这个）
`durationSec`	`number`	时长（秒）
`distanceMeters`	`number`	距离（米）
`avgPaceSecPerKm`	`number \| null`	平均配速（秒/公里）
`avgHeartRate`	`number \| null`	平均心率（bpm）
`maxHeartRate`	`number \| null`	最大心率（bpm）
`avgCadence`	`number \| null`	平均步频（spm）
`elevationGainMeters`	`number \| null`	累计爬升（米）
`calories`	`number \| null`	热量（kcal）
`runScore`	`number \| null`	单跑综合评分 0–100（平台算法）
`trainingLoad`	`number \| null`	训练负荷 TRIMP（Banister，平台算法）
`isRace`	`boolean`	是否比赛（匹配到赛事库）
`raceName`	`string \| null`	赛事名称
`location`	`string \| null`	地点（城市/POI）
`deviceName`	`string \| null`	记录设备
`source`	`string`	数据来源：GARMIN / COROS / SUUNTO / ZEPP / KEEP 等
`splits`	`object[]`	每公里分段（最多 100 段）
`splits[].km`	`number`	第几段（按公里切分，1、2、3…）
`splits[].distanceMeters`	`number \| null`	该段距离（米）；按公里切分，末段为剩余距离
`splits[].durationSec`	`number`	该段耗时（秒）
`splits[].paceSecPerKm`	`number`	该段配速（秒/公里）
`splits[].avgHeartRate`	`number \| null`	平均心率
`splits[].avgCadence`	`number \| null`	平均步频
`splits[].elevationGainMeters`	`number \| null`	爬升（米）
`laps`	`object[]`	圈次（最多 50 圈；间歇课的工作/休息段在此）
`laps[].lap`	`number`	圈序号
`laps[].distanceMeters`	`number`	距离（米）
`laps[].durationSec`	`number`	耗时（秒）
`laps[].paceSecPerKm`	`number`	配速（秒/公里）
`laps[].avgHeartRate`	`number \| null`	平均心率
`laps[].maxHeartRate`	`number \| null`	最大心率
`laps[].avgCadence`	`number \| null`	平均步频
`laps[].intensity`	`string \| null`	圈类型：ACTIVE（工作段）/ REST（休息段）/ WARMUP / COOLDOWN 等
`hasIntervalStructure`	`boolean`	圈次是否构成结构化间歇课
`heartRateZones`	`object[]`	心率区间分布
`heartRateZones[].zone`	`number`	区间 1–5
`heartRateZones[].label`	`string`	区间名
`heartRateZones[].timeSec`	`number`	区间内时长（秒）
`heartRateZones[].percentage`	`number`	占比 0–100
`paceZones`	`object[]`	配速区间分布
`paceZones[].zone`	`number`	区间 1–5
`paceZones[].label`	`string`	区间名
`paceZones[].timeSec`	`number`	区间内时长（秒）
`paceZones[].percentage`	`number`	占比 0–100
`halfSplit`	`object \| null`	前后半程对比
`halfSplit.firstHalf`	`object`
`halfSplit.firstHalf.distanceMeters`	`number`	半程距离
`halfSplit.firstHalf.durationSec`	`number`	半程耗时
`halfSplit.firstHalf.paceSecPerKm`	`number`	半程配速
`halfSplit.firstHalf.avgHeartRate`	`number \| null`	半程平均心率
`halfSplit.secondHalf`	`object`
`halfSplit.secondHalf.distanceMeters`	`number`	半程距离
`halfSplit.secondHalf.durationSec`	`number`	半程耗时
`halfSplit.secondHalf.paceSecPerKm`	`number`	半程配速
`halfSplit.secondHalf.avgHeartRate`	`number \| null`	半程平均心率
`runningDynamics`	`object \| null`	跑步动态
`runningDynamics.avgGroundContactTimeMs`	`number \| null`	平均触地时间（毫秒）
`runningDynamics.avgVerticalOscillationCm`	`number \| null`	平均垂直振幅（厘米）
`runningDynamics.avgVerticalRatioPct`	`number \| null`	平均垂直步幅比（%）
`runningDynamics.avgStrideLengthMeters`	`number \| null`	平均步幅（米）
`trainingEffect`	`object \| null`	设备训练效果
`trainingEffect.aerobicTE`	`number \| null`	有氧训练效果 0–5
`trainingEffect.anaerobicTE`	`number \| null`	无氧训练效果 0–5
`bestEfforts`	`object[]`	本次活动内各标准距离的最佳段
`bestEfforts[].distanceName`	`string`	距离名，如 5公里
`bestEfforts[].durationSec`	`number`	该距离最佳用时（秒）
`bestEfforts[].paceSecPerKm`	`number`	配速
`bestEfforts[].isPersonalBest`	`boolean`	是否刷新个人最佳
`bestEfforts[].rank`	`number \| null`	在个人历史中的名次（1–5）
`achievements`	`object[]`	本次解锁的成就
`achievements[].name`	`string`
`achievements[].description`	`string`
`runScoreBreakdown`	`object \| null`	综合评分四分量（缺数分量为 null，不参与加权）
`runScoreBreakdown.intent`	`number \| null`	A 意图–执行匹配 0–100；null=缺数
`runScoreBreakdown.performance`	`number \| null`	B 发挥 0–100；null=无达成率
`runScoreBreakdown.cost`	`number \| null`	C 心率–配速解耦 0–100；null=缺数或非稳态课型
`runScoreBreakdown.context`	`number \| null`	D 上下文调整 50–100；null=无高温/疲劳补偿
`temperatureC`	`number \| null`	平均气温（℃，设备记录）
`workoutRpe`	`number \| null`	主观强度 RPE（设备记录）

`get_personal_bests`个人最佳

各标准距离（1K/5K/10K/半马/全马等）与最长距离/最长时长的个人 Top 5 记录，可按时间窗口筛选。

参数

名称	类型	必填	默认	说明
`recordType`	`string`	否	—	只取某一类，如 DIST_5K / DIST_10K / DIST_HALF / DIST_MARATHON；默认全部
`period`	`"ALL_TIME" \| "RECENT_6M" \| "RECENT_1Y"`	否	`"ALL_TIME"`	时间窗口

返回字段（10）

字段	类型	说明
`groups`	`object[]`
`groups[].recordType`	`string`	记录类型，如 DIST_5K / DIST_10K / DIST_HALF / DIST_MARATHON / LONGEST_DISTANCE
`groups[].name`	`string`	中文名
`groups[].unit`	`string`	记录值单位：duration（秒）/ distance（米）
`groups[].records`	`object[]`
`groups[].records[].rank`	`number`	名次 1–5
`groups[].records[].value`	`number`	记录值（按 unit）
`groups[].records[].paceSecPerKm`	`number \| null`	配速（距离类记录）
`groups[].records[].activityId`	`string`	对应活动 ID
`groups[].records[].achievedAt`	`string`	达成时间（ISO 8601）

`get_race_predictions`成绩预测

基于当前能力状态模型的 5K / 10K / 半马 / 全马完赛时间预测（含区间与置信度）及对应个人最佳。

参数

无

返回字段（8）

字段	类型	说明
`predictions`	`object[]`
`predictions[].distanceMeters`	`number`	距离（米）
`predictions[].distanceLabel`	`string`	5K / 10K / 半马 / 全马
`predictions[].predictedTimeSec`	`number`	预测完赛时间（秒，典型发挥）
`predictions[].lowSec`	`number \| null`	区间下限（顺利发挥）
`predictions[].highSec`	`number \| null`	区间上限
`predictions[].confidence`	`number \| null`	置信度 0–1
`predictions[].pbTimeSec`	`number \| null`	个人最佳（秒）

`get_training_status`训练状态

当前训练状态总览：体能/疲劳/状态（CTL/ATL/TSB 及分级）、跑力指数 RPI 与近期变化、负荷质量、能力五轴分位、比赛执行画像。

参数

无

返回字段（47）

字段	类型	说明
`date`	`string \| null`	快照日期 YYYY-MM-DD；null=尚无数据
`fitness`	`object \| null`
`fitness.ctl`	`number`	体能 CTL（42 天负荷 EWMA）
`fitness.atl`	`number`	疲劳 ATL（7 天负荷 EWMA）
`fitness.tsb`	`number`	状态 TSB = CTL − ATL
`fitness.tsbLabel`	`string`	TSB 分级：fresh / neutral / fatigued / overreaching
`fitness.tsbTitle`	`string`	TSB 分级中文标题
`fitness.tsbSubtitle`	`string`	TSB 分级说明
`fitness.ctlLabel`	`string`	CTL 分级
`fitness.ctlTitle`	`string`	CTL 分级中文标题
`runPowerIndex`	`number \| null`	跑力指数 RPI 0–110（纯能力合成）
`runPowerIndexDelta`	`object`
`runPowerIndexDelta.d1`	`number \| null`	较昨日
`runPowerIndexDelta.w4`	`number \| null`	较 4 周前
`runPowerIndexDelta.w6`	`number \| null`	较 6 周前
`runPowerIndexDelta.m6`	`number \| null`	较 6 个月前
`ctlDelta4w`	`number \| null`	CTL 较 4 周前变化
`loadQuality`	`object \| null`
`loadQuality.monotony`	`number \| null`	7 日单调性（Foster）
`loadQuality.strain`	`number \| null`	7 日 strain
`loadQuality.ctlRamp7d`	`number \| null`	CTL 周爬升
`loadQuality.efTrend`	`number \| null`	效率因子 EWMA
`efDelta6wPct`	`number \| null`	跑步效率 6 周变化 %
`confidence`	`number \| null`	快照数据可用性置信度 0–1
`abilities`	`object \| null`	能力五轴；null=尚无数据
`abilities.aerobic`	`object \| null`	有氧能力轴
`abilities.aerobic.score`	`number`	同龄同性别分位 0–100（缺性别/生日时等同 scoreOverall）
`abilities.aerobic.scoreOverall`	`number`	全站分位 0–100
`abilities.cruise`	`object \| null`	巡航（阈值）能力轴
`abilities.cruise.score`	`number`	同龄同性别分位 0–100（缺性别/生日时等同 scoreOverall）
`abilities.cruise.scoreOverall`	`number`	全站分位 0–100
`abilities.endurance`	`object \| null`	续航耐力轴
`abilities.endurance.score`	`number`	同龄同性别分位 0–100（缺性别/生日时等同 scoreOverall）
`abilities.endurance.scoreOverall`	`number`	全站分位 0–100
`abilities.economy`	`object \| null`	跑姿经济性轴（实验性）
`abilities.economy.score`	`number`	同龄同性别分位 0–100（缺性别/生日时等同 scoreOverall）
`abilities.economy.scoreOverall`	`number`	全站分位 0–100
`abilities.resilience`	`object \| null`	肌肉韧性轴（实验性）
`abilities.resilience.score`	`number`	同龄同性别分位 0–100（缺性别/生日时等同 scoreOverall）
`abilities.resilience.scoreOverall`	`number`	全站分位 0–100
`abilities.ageGroup`	`string \| null`	同龄组名
`abilities.cruisePaceSecPerKm`	`number \| null`	巡航配速（秒/公里，≈阈值配速）
`abilities.raceExecution`	`object`	比赛执行画像
`abilities.raceExecution.meanLossVdot`	`number`	比赛平均发挥损耗（VDOT）
`abilities.raceExecution.effectiveRaces`	`number`	有效比赛场次
`abilities.raceExecution.paceLossSecPerKm`	`number \| null`	换算：每公里配速损失（秒）
`abilities.confidenceScore`	`number`	能力估计置信度 0–1

`get_fitness_trend`体能趋势

最近 N 天逐日的 CTL / ATL / TSB / 跑力指数 / ACWR 序列（默认 42 天，最多 180 天）。

参数

名称	类型	必填	默认	说明
`days`	`integer`	否	`42`	回看天数

返回字段（7）

字段	类型	说明
`points`	`object[]`
`points[].date`	`string`	YYYY-MM-DD
`points[].ctl`	`number`	体能
`points[].atl`	`number`	疲劳
`points[].tsb`	`number`	状态
`points[].runPowerIndex`	`number`	跑力指数
`points[].acwr`	`number \| null`	急慢性负荷比（EWMA-ACWR）；训练史不足为 null

`get_wellness`恢复与健康

逐日恢复信号：HRV（相对个人基线的 z 分与状态）、静息心率与漂移、睡眠时长/评分/分期及 30 日基线、压力。默认截至今天回看 7 天，最多 30 天；可用 to 回看历史。

参数

名称	类型	必填	默认	说明
`days`	`integer`	否	`7`	回看天数
`to`	`string`	否	—	区间结束日 YYYY-MM-DD（含），默认今天

返回字段（21）

字段	类型	说明
`days`	`object[]`
`days[].date`	`string`	YYYY-MM-DD（当日；睡眠/HRV 指前一夜）
`days[].hrv`	`object`
`days[].hrv.lastNightMs`	`number \| null`	昨夜 HRV 均值（ms，原始）
`days[].hrv.z`	`number \| null`	7 日均值相对 60 日个人基线的 z 分
`days[].hrv.status`	`string \| null`	normal / low / elevated；null=基线样本不足
`days[].restingHr`	`object`
`days[].restingHr.value`	`number \| null`	当日静息心率
`days[].restingHr.mean7d`	`number \| null`	7 日均值
`days[].restingHr.mean60d`	`number \| null`	60 日均值
`days[].restingHr.drift`	`number \| null`	7d − 60d（bpm，正值=漂高预警）
`days[].sleep`	`object`
`days[].sleep.seconds`	`number \| null`	睡眠时长（秒）
`days[].sleep.score`	`number \| null`	睡眠评分（设备）
`days[].sleep.deepSec`	`number \| null`	深睡
`days[].sleep.lightSec`	`number \| null`	浅睡
`days[].sleep.remSec`	`number \| null`	REM
`days[].sleep.awakeSec`	`number \| null`	清醒
`days[].sleep.mean30dSec`	`number \| null`	30 日睡眠时长均值
`days[].sleep.scoreMean30d`	`number \| null`	30 日评分均值
`days[].stressAvg`	`number \| null`	日均压力（设备）

`get_weekly_report`训练周报

AI 教练生成的训练周报：叙事正文、本周跑量、计划执行、体能变化、负荷护栏、进步信号、恢复概览。缺省取最近一份。

参数

名称	类型	必填	默认	说明
`periodKey`	`string`	否	—	周期键 = 该周周一日期 YYYY-MM-DD；缺省最近一份

返回字段（38）

字段	类型	说明
`report`	`object \| null`	null=该周期无周报
`report.periodKey`	`string`	周期键（周一日期 YYYY-MM-DD）
`report.fromDate`	`string`
`report.toDate`	`string`
`report.verdict`	`string`	on_track / attention / warning
`report.narrative`	`string`	教练周报正文
`report.runTotals`	`object \| null`
`report.runTotals.runs`	`number`	跑步次数
`report.runTotals.km`	`number`	公里
`report.runTotals.durationMin`	`number`	分钟
`report.plan`	`object \| null`	计划执行面；无计划为 null
`report.plan.plannedSessions`	`number`	计划课次
`report.plan.completedSessions`	`number`	完成课次
`report.plan.completionPct`	`number`	完成率 %
`report.plan.plannedKm`	`number`	计划公里
`report.plan.actualKm`	`number`	实际公里
`report.fitness`	`object`
`report.fitness.ctlDelta`	`number \| null`	CTL 周变化
`report.fitness.tsbEnd`	`number \| null`	周末 TSB
`report.fitness.runPowerIndexDelta`	`number \| null`	跑力周变化
`report.acwr`	`object \| null`
`report.acwr.value`	`number`	急慢性负荷比
`report.acwr.status`	`string`
`report.acwr.description`	`string`
`report.progress`	`object \| null`
`report.progress.pbs`	`object[]`
`report.progress.pbs[].label`	`string`
`report.progress.pbs[].valueFormatted`	`string`
`report.progress.effectiveVdotDelta`	`number \| null`	有氧能力周变化
`report.progress.racePredictionDeltas`	`object[]`
`report.progress.racePredictionDeltas[].distanceLabel`	`string`
`report.progress.racePredictionDeltas[].deltaSec`	`number`	秒，负=变快
`report.wellness`	`object \| null`
`report.wellness.daysWithData`	`number`
`report.wellness.sleepAvgHours`	`number \| null`	周均睡眠（小时）
`report.wellness.hrvLowDays`	`number`	HRV 偏低天数
`report.wellness.rhrDriftEnd`	`number \| null`	周末静息心率漂移
`report.generatedAt`	`string`

`get_monthly_report`训练月报

AI 教练生成的月度总结：当月跑量、各周概览、里程碑（PB / 最长跑）、体能变化、叙事正文。

参数

名称	类型	必填	默认	说明
`periodKey`	`string`	是	—	月份 YYYY-MM

返回字段（28）

字段	类型	说明
`report`	`object \| null`	null=该月无月报
`report.periodKey`	`string`	YYYY-MM
`report.fromDate`	`string`
`report.toDate`	`string`
`report.totals`	`object`
`report.totals.runs`	`number`
`report.totals.km`	`number`
`report.totals.durationMin`	`number`
`report.totals.trainingDays`	`number`
`report.weeks`	`object[]`
`report.weeks[].periodKey`	`string`
`report.weeks[].km`	`number`
`report.weeks[].runs`	`number`
`report.weeks[].verdict`	`string \| null`	周结论；null=该周无周报
`report.weeks[].focus`	`string[]`	该周叙事主题
`report.milestones`	`object`
`report.milestones.pbs`	`object[]`
`report.milestones.pbs[].label`	`string`
`report.milestones.pbs[].valueFormatted`	`string`
`report.milestones.longestRun`	`object \| null`
`report.milestones.longestRun.date`	`string`
`report.milestones.longestRun.distanceKm`	`number`
`report.fitness`	`object`
`report.fitness.ctlDelta`	`number \| null`
`report.fitness.runPowerIndexDelta`	`number \| null`
`report.fitness.effectiveVdotDelta`	`number \| null`
`report.narrative`	`string`	月度总结正文
`report.generatedAt`	`string`

限制与安全

协议: MCP Streamable HTTP（无状态，仅 POST；响应为 JSON）
鉴权: Authorization: Bearer <令牌>；无效 / 吊销 / 过期返回 401
调用频率: 每令牌 60 次/分钟、5000 次/天；超限返回 429 并带 Retry-After
并发: 每令牌同时最多 3 个请求
令牌: 每账号最多 5 个有效令牌；有效期 1 年；可随时吊销
数据范围: list_activities 单次最多跨 366 天、每页 50 条；趋势最多 180 天；恢复数据最多 30 天

常见问题

令牌泄露了怎么办？

到小程序「AI 助手接入」里吊销它，立即失效；再创建一个新的即可。

为什么 claude.ai 网页版 / ChatGPT 里添加不了？

这两个平台的自定义连接器要求 OAuth 登录授权，目前我们只提供令牌方式；OAuth 接入在计划中。WorkBuddy、OpenClaw、Claude Code、Cursor 等支持自定义请求头的客户端均可使用。

返回的数据和小程序里看到的一致吗？

一致，同一套计算结果。少数字段做了取整（距离取整到米、配速到秒）。

会返回我的 GPS 轨迹吗？

不会。MCP 只返回摘要、每公里分段、圈次与各项分析指标，不返回轨迹点与逐秒心率/配速流。

时间、距离、配速的单位？

时长一律秒，距离一律米，配速一律秒/公里；日期为 YYYY-MM-DD。活动开始时间为 RFC 3339 并带活动当地时区偏移（如 2026-08-23T06:30:00+08:00，海外活动为当地偏移），另有 date 字段直接给当地日期。

变更记录

v1.0.0 · 2026-08

首发：档案 / 活动列表与详情 / 个人最佳 / 成绩预测 / 训练状态与趋势 / 恢复数据 / 周报月报，共 10 个只读 tool