Intervals.icu MCP 服务器与 AI 跑步教练

面向 Intervals.icu 的官方级 模型上下文协议（MCP）服务器 与 AI 跑步教练智能系统。

让您的 AI 助手（Claude Desktop、Antigravity、Cursor、VS Code Cline / Roo-Code）能够读取实时遥测数据、评估急性和慢性训练负荷（CTL/ATL/TSB/ACWR）、计算 Jack Daniels VDOT 与配速区间、计算心率漂移与有氧解耦、预测比赛成绩、安排减量训练，并直接将结构化训练计划发布到您的 Intervals.icu 日历中。

📑 目录

• ✨ 核心能力

• 🚀 3 分钟快速上手

• ⚙️ 配置（API 密钥与运动员 ID）

• 🔌 MCP 客户端设置指南

  • Claude Desktop

  • Antigravity

  • Cursor

  • VS Code（Cline / Roo-Code）

• 🤖 AI 工作流与斜杠命令目录

• 👤 自定义您的运动员档案

• 💬 示例聊天提示

• 🛠️ 完整 MCP 工具参考

• 🧪 开发与测试

• 📄 许可证

Related MCP server: Intervals.icu MCP Server

✨ 核心能力

• 🏃 实时遥测与数据流摄取：从已完成训练中提取功率、心率、踏频、速度和分段数据。

• ⚡ 有氧解耦与心率漂移引擎：计算效率因子（EF）$H_1$ 与 $H_2$，以检测心血管漂移（>5%）或脱水。

• 🩹 统一恢复与准备状态评分：综合 TSB、ACWR、睡眠评分、HRV 和静息心率突增，得出 0–100% 的综合评分，并转化为绿/黄/红行动信号。

• 🏆 比赛成绩预测与减量规划器：Jack Daniels VDOT 公式 + CTL 体能和 TSB 状态调整 + 2–3 周训练量递减生成器。

• ⚖️ ACWR 与周训练量预算：基于 42 天滚动基线，提供安全的训练量递增上限（长跑 30–35%、质量课 15–20%、轻松跑 45–55%）。

• 📅 结构化训练计划构建器：使用 Intervals 原生文本 DSL（Warmup、Main Set Nx、Cooldown）将训练计划发布到 Intervals.icu 日历。

🚀 3 分钟快速上手

1. 前置条件

• Node.js：>= 18.0.0

• 包管理器：pnpm（推荐）、npm 或 yarn

• Intervals.icu 账户与 API 密钥

2. 克隆与构建

git clone https://github.com/hadidwirsty/intervals-icu-mcp.git
cd intervals-icu-mcp
pnpm install
pnpm run build

⚙️ 配置

从 Intervals.icu 设置 获取您的凭据：

1. 向下滚动到 开发者 部分。

2. 复制您的 API 密钥（例如 your_api_key_here）。

3. 记下您的 运动员 ID（可在设置或个人资料 URL 中找到，例如 i12345，或使用 self）。

环境变量

🔌 MCP 客户端设置指南

1. Claude Desktop

将以下内容添加到您的 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/intervals-icu-mcp/dist/index.js"],
      "env": {
        "INTERVALS_API_KEY": "YOUR_API_KEY_HERE",
        "INTERVALS_ATHLETE_ID": "self"
      }
    }
  }
}

2. Antigravity

在您的 Antigravity MCP 设置或 .gemini/config/mcp.json 中：

{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/intervals-icu-mcp/dist/index.js"],
      "env": {
        "INTERVALS_API_KEY": "YOUR_API_KEY_HERE",
        "INTERVALS_ATHLETE_ID": "self"
      }
    }
  }
}

3. Cursor

在 Cursor 设置 > 功能 > MCP 服务器或 .cursor/mcp.json 中：

{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/intervals-icu-mcp/dist/index.js"],
      "env": {
        "INTERVALS_API_KEY": "YOUR_API_KEY_HERE",
        "INTERVALS_ATHLETE_ID": "self"
      }
    }
  }
}

4. VS Code（Cline / Roo-Code）

在 cline_mcp_settings.json 中：

{
  "mcpServers": {
    "intervals-icu": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/intervals-icu-mcp/dist/index.js"],
      "env": {
        "INTERVALS_API_KEY": "YOUR_API_KEY_HERE",
        "INTERVALS_ATHLETE_ID": "self"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

🤖 AI 工作流与斜杠命令目录

本仓库预装了 .agents/workflows/ 目录下的 11 个生产级 AI 工作流，您可以通过斜杠命令触发：

👤 自定义您的运动员档案

为了让您的 AI 助手获得准确的教练上下文，请在 .agents/skills/running-coach-analysis/SKILL.md 中配置您的档案：

1. 第 2 节（运动员档案）：填写您的姓名、年龄、备用体重和目标比赛目标。

2. 第 3 节（生理基线）：提供备用 CP/FTP、LTHR、最大心率和静息心率（注意：活跃值会通过 MCP 自动动态同步）。

3. 第 4 节（每周结构与蓝图）：定义您的每周训练频率、偏好的训练课类型（例如阈值下、VO2Max、长跑）以及具体的功率/配速目标。

💬 示例聊天提示

以下是与您的 AI 跑步教练对话的一些示例：

1. 每日跑后评估

"这是我今天早上的训练。请对我的最新活动运行 /run-report。RPE 为 6/10，第 3 组间歇时腿部感觉很有弹性。"

2. 训练前准备状态检查

"/readiness-check — 我今天的状态是否足以完成阈值下间歇训练，还是应该将强度限制在 2 区？"

3. 每周训练量分配

"/weekly-budget distance — 我本周的推荐总里程和长跑上限是多少？"

4. 比赛日预测与减量

"/predict-race — 我的当前 VDOT 为 50，目标半程马拉松比赛日期为 2026-10-15。请给我完赛时间预测和 2 周减量计划。"

5. 将训练安排到日历

"/create-workout — 为明天安排一次 50 分钟的阈值下训练（热身 12 分钟，6x3 分钟 @ 95-98% CP，每组间休息 1 分钟，放松 6 分钟）。"

🛠️ 完整 MCP 工具参考

服务器提供 20+ 个工具，按类别分组：

🏃 1. 活动与数据流

• get_activities：获取日期范围内的活动（oldest、newest、type）。

• get_activity_details：按活动 ID 检索完整遥测数据、指标和运动员生理值。

• get_activity_intervals：提取圈数和训练/休息分段明细。

• get_activity_streams：访问原始时间序列流数据（watts、heartrate、cadence、velocity_smooth、altitude）。

• get_activity_messages：读取活动评论和备注。

• add_activity_message：向活动发布教练反馈。

👤 2. 运动员生物特征与区间

• get_athlete_profile：检索运动员档案（FTP、LTHR、最大心率、体重、静息心率）。

• get_training_zones：访问功率、心率和配速训练区间边界。

🧮 3. 生理与耐力智能（离线）

• calculate_vdot：根据比赛/节奏计时赛计算 Jack Daniels VDOT 与 VO₂max。

• calculate_pace_zones：以 MM:SS/km 为单位计算 5 个配速训练区间（轻松、马拉松、阈值、间歇、重复）。

• predict_race_time：根据 VDOT 预测比赛完赛时间和配速（5K、10K、半马、全马或自定义公里数），并结合 CTL 体能和 TSB 状态调整。

• calculate_taper_plan：生成每周训练量递减计划（75% → 50% → 30%），以在比赛日达到峰值 TSB 状态。

• analyze_cardiac_drift：根据原始遥测数据流（heartrateStream、powerOrSpeedStream）计算效率因子（EF）和有氧解耦百分比。

• calculate_readiness_score：计算综合恢复评分（0–100%，绿/黄/红），结合 TSB、ACWR、睡眠、HRV 和静息心率。

⚖️ 4. 训练负荷与周期化（离线）

• analyze_training_load：计算 ACWR（ATL/CTL）、分类 TSB 准备状态区间，并评估爬升率受伤风险。

• calculate_weekly_budget：基于 42 天滚动平均值计算每周安全训练预算（总训练量、长跑 30–35%、质量课 15–20%、轻松跑 45–55%）。

📅 5. 日历与训练计划构建器

• get_events：检索日期范围内的日历项目（计划训练、备注、比赛）。

• get_event_by_id：按 ID 获取详细事件数据。

• create_running_workout：结构化训练计划构建器 — 使用文本 DSL 验证并将结构化训练发布到 Intervals.icu 日历。

• add_or_update_planned_workout：创建或更新计划训练事件。

• add_or_update_note：向日历日期添加文本备注。

• delete_event：按 ID 删除日历事件。

• get_workout_library：搜索训练模板库。

• get_workout_by_id：获取训练模板详情。

🚴 6. 装备与功率曲线

• get_gear_list：列出已注册的自行车、跑鞋和装备及其里程（缓存 30 分钟）。

• get_athlete_power_curves：获取功率持续时间曲线（缓存 60 分钟）。

💚 7. 健康与体能时间序列

• get_wellness_data：检索每日健康条目（睡眠评分、HRV、静息心率、疲劳、酸痛、体重）。

• get_fitness_chart：检索时间序列健身数据（ctl、atl、tsb、rampRate、eftp）。

🧪 开发与测试

运行完整的单元测试套件：

# Run Vitest unit tests
pnpm test

# Build TypeScript
pnpm run build

# Watch mode during development
pnpm exec vitest

包含 59+ 个单元测试，涵盖 API 客户端在 HTTP 429 时的自动重试、LRU TTL 缓存、Jack Daniels VDOT 数学计算、比赛预测、心脏漂移分析、恢复评分、ACWR 分析和锻炼 DSL 验证。

📄 许可证

本项目根据 MIT 许可证 授权，© Muhammad Hadid Wiransetyo。