IGPSPORT-MCP

igpsport-mcp

English | 简体中文

一个本地 MCP 服务，可将你的 iGPSport 骑行数据连接到 Claude 等大模型客户端。用自然语言分析训练情况：“我这周的训练负荷如何？” “比较一下我上周和这周的两次长距离骑行。” “我在收藏的那段爬坡路段排名如何？” “我今年骑了多少公里，有哪些个人最佳成绩？” —— 你甚至可以让 Claude 为你制定训练计划：“根据我的 FTP 为我制定一堂 2×20 SST 训练课，并推送到我的码表。”

主要优势：衍生训练指标——NP / IF / TSS / CTL / ATL / TSB——会在返回前由 MCP 层在服务端计算。大模型收到的是可直接用于分析的数字，而不是原始数据流。

You:   What's my training load trend over the last 90 days? Should I back off?
Claude (via analyze_training_load):
       Current CTL (Fitness) 72, ATL (Fatigue) 91, TSB (Form) -19 — you're in a significant fatigue hole.
       TSS has been above CTL for the past two weeks. Consider a 3–5 day recovery block to get TSB back above -5…

演示

⚠️ 非官方项目。此工具通过模拟 iGPSport Web 客户端请求运行。iGPSport 可能随时更改其 API，导致功能失效。请自行评估账号风险——使用风险自负。工具完全在本地通过 stdio 运行——你的数据绝不会经过任何第三方服务器。

快速开始（推荐）

此工具是一个 MCP 服务，需要使用支持 MCP 的客户端（例如 Claude Desktop / Claude Code / Cursor）。准备好客户端后，按以下三步操作：

1. 安装 uv（一个独立工具——无需预先安装 Python，uv 会自动处理运行时）：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 全局安装并运行设置向导（交互式输入手机号/电子邮箱和密码——凭据会保留在本地）。两种系统的命令相同；在 macOS 上使用终端运行，在 Windows 上使用 PowerShell 运行：

uv tool install igpsport-mcp
igpsport-mcp --setup

如果安装后找不到 igpsport-mcp，请打开新的终端/PowerShell 窗口，让 PATH 更新生效（uv 会在 macOS 上将可执行文件放在 ~/.local/bin，在 Windows 上放在 %USERPROFILE%\.local\bin）。

向导会将凭据保存到配置文件（仅所有者可读取），并输出一段可直接复制粘贴的 MCP 配置。配置文件位置：

• macOS：~/.igpsport-mcp/config.json
• Windows：C:\Users\YourName\.igpsport-mcp\config.json

3. 将输出的配置粘贴到客户端中，然后重启客户端（参见下文“连接到 Claude”）。

想在粘贴前验证凭据？运行 igpsport-mcp --check——它会实际登录并显示 ✅ 成功，或 ❌ 失败原因，这样你就不会把无法使用的配置添加到客户端中。

之后需要再次输出配置片段？随时运行 igpsport-mcp --mcp-config。

---

开发者 / 已有 Python 环境的用户：可使用 uvx igpsport-mcp 运行一次性任务，或改用下方的环境变量进行配置，无需使用向导。

CLI 用法

不带任何参数运行时，会以 stdio 模式启动 MCP 服务（MCP 客户端会调用此命令——通常无需手动运行）。其他子命令：

命令	用途
igpsport-mcp --setup	交互式设置向导：输入手机号/电子邮箱和密码，并保存到本地 config.json
igpsport-mcp --mcp-config	输出可直接复制粘贴的 MCP 客户端配置块
igpsport-mcp --check	实际登录以验证凭据（账号会以掩码形式显示）
igpsport-mcp --lang en|zh	设置输出语言（也可通过 IGPSPORT_LANG 环境变量设置；默认为 zh）
igpsport-mcp --version	输出版本号
igpsport-mcp --help	显示帮助

配置（环境变量）

运行过 --setup 向导的用户可以跳过本节——凭据已保存。下文适用于偏好使用环境变量，或需要在 CI / 多个环境间管理凭据的用户。环境变量的优先级高于 config.json。

变量	必填	说明
IGPSPORT_USERNAME	✅	iGPSport 账号（中国区使用手机号 / 国际区使用邮箱）
IGPSPORT_PASSWORD	✅	密码
IGPSPORT_REGION	可选	区域，默认 cn（中国服务器 app.igpsport.cn）；国际区用户设为 intl（app.igpsport.com）
IGPSPORT_FTP	可选	功能性阈值功率，单位为瓦。留空可自动读取 iGPSport 个人资料中的数值；设置后将覆盖
IGPSPORT_LTHR	可选	乳酸阈值心率，单位为 bpm，用于心率区间和 hrTSS 回退计算。也会自动从 iGPSport 读取；设置后将覆盖
IGPSPORT_LANG	可选	输出语言，zh（默认）或 en
IGPSPORT_CACHE_DIR	可选	缓存目录；默认为 ~/.cache/igpsport-mcp（macOS）/ C:\Users\You\.cache\igpsport-mcp（Windows）
IGPSPORT_LOG_LEVEL	可选	默认为 INFO

默认情况下，FTP / LTHR 现在会从你的 iGPSport 运动员资料中自动读取（同时也会读取体重和最大心率），所以通常无需手动设置。只有在你想使用与应用中不同的阈值时，才需要设置环境变量。如果你的 iGPSport 资料中也未设置 FTP，则无法计算 IF / TSS / CTL / ATL / TSB——请在 iGPSport 中添加 FTP，或设置 IGPSPORT_FTP。

国际版支持

设置 IGPSPORT_REGION=intl，即可切换到国际版（app.igpsport.com）。国际版和中国区服务器使用独立账号——你必须在 app.igpsport.com 单独注册。

与中国区服务器的差异：

• 无 WASM 签名——身份验证使用纯 JWT，设计更简单
• 不提供分段功能（国际版分段功能仍处于测试阶段，列表为空）
• 训练参数端点使用 v2 路径；年度统计路径不同（内部会自动适配）
• 训练课程格式跨区域兼容——IR 编译层无需任何改动

配置示例：

# via env vars
export IGPSPORT_REGION=intl
export [email protected]
export IGPSPORT_PASSWORD=your_password

或者在 --setup 向导的第一步中选择“2. International”。

国际版的 FIT 文件存储在美国的 OSS（oss-us-west-1）上。中国用户下载速度可能稍慢。

连接到 Claude

Claude Desktop

打开配置文件 claude_desktop_config.json（如果不存在，请创建），粘贴下方内容，然后完全退出并重新打开 Claude Desktop。文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json（即 C:\Users\You\AppData\Roaming\Claude\claude_desktop_config.json）

你也可以在 Claude Desktop 中通过设置 → 开发者 → 编辑配置直接打开此文件。

运行 --setup 后（凭据已存入 config.json，将 env 留空——这是 --mcp-config 输出的内容）：

{
  "mcpServers": {
    "igpsport": {
      "command": "igpsport-mcp",
      "args": [],
      "env": {}
    }
  }
}

或者跳过向导，使用带环境变量的 uvx：

{
  "mcpServers": {
    "igpsport": {
      "command": "uvx",
      "args": ["igpsport-mcp"],
      "env": {
        "IGPSPORT_USERNAME": "your_phone_or_email",
        "IGPSPORT_PASSWORD": "your_password"
      }
    }
  }
}

FTP / LTHR 默认会从你的 iGPSport 资料中自动读取，无需设置。只有在你想覆盖应用中的数值时，才在 env 中添加 "IGPSPORT_FTP": "250" 或 "IGPSPORT_LTHR": "160"。

Claude Code

运行向导后（凭据已保存）：

claude mcp add igpsport --scope user -- igpsport-mcp

或者使用 uvx + 环境变量：

claude mcp add igpsport --scope user \
  --env IGPSPORT_USERNAME=your_phone_or_email \
  --env IGPSPORT_PASSWORD=your_password \
  -- uvx igpsport-mcp

使用 /mcp 或 claude mcp list 验证——状态应为 connected。

OpenClaw

OpenClaw 使用 stdio 进行 MCP 通信，与 Claude Desktop / Claude Code 使用相同的协议，因此上述配置可以直接使用。

方法 1：用自然语言向 OpenClaw 提问（推荐）

先使用 uv tool install igpsport-mcp 安装，然后运行 igpsport-mcp --setup。接着，在已连接的聊天频道中，只需告诉 OpenClaw：

我安装了 igpsport-mcp。请帮我在 OpenClaw 中配置它。

它会查找二进制文件路径，使用 igpsport-mcp --check 验证凭据，通过 openclaw mcp add 写入配置并进行探测，整个过程无需你操作命令行或 JSON。

方法 2：一行命令

# After the wizard (credentials stored)
openclaw mcp add igpsport --command igpsport-mcp

# Or with uvx + env vars
openclaw mcp add igpsport --command uvx --args igpsport-mcp \
  --env IGPSPORT_USERNAME=your_phone_or_email \
  --env IGPSPORT_PASSWORD=your_password

这会将配置写入 ~/.openclaw/openclaw.json 中的 mcp.servers.igpsport。你也可以手动编辑该文件：

{
  mcp: {
    servers: {
      igpsport: {
        command: "igpsport-mcp",
        args: [],
        env: {}
      }
    }
  }
}

验证：

openclaw mcp list      # should show igpsport
openclaw mcp status    # igpsport: stdio
openclaw mcp probe     # igpsport: 17 tools, resources, prompts

mcp 字段支持热重载，无需重启网关；它会在下一轮对话中生效。如有需要，可使用 openclaw mcp reload 强制刷新运行时缓存。然后，你就可以在任何已连接的频道（Discord、Telegram、Slack 等）中用自然语言提问。

无法连接？ 先在终端中运行 igpsport-mcp --check，以排查问题：

• ❌ 登录失败 → 凭据问题；重新运行 igpsport-mcp --setup。

• ✅ 验证成功，但客户端仍无法连接 → 可能是客户端的 PATH 中没有 igpsport-mcp / uvx（尤其是 Claude Desktop 通常无法读取登录 Shell 的 PATH）。请将配置中的 command 替换为绝对路径：

• macOS：在 Terminal 中运行 which igpsport-mcp（或 which uvx），例如 /Users/You/.local/bin/igpsport-mcp。

• Windows：在 PowerShell 中运行 where.exe igpsport-mcp（或 where.exe uvx），例如 C:\Users\You\.local\bin\igpsport-mcp.exe。在 JSON 中，反斜杠必须加倍，例如 "command": "C:\\Users\\You\\.local\\bin\\igpsport-mcp.exe"。

更新

对于通过 uv tool install 安装的用户（两种系统均适用），升级到最新版本：

uv tool upgrade igpsport-mcp

升级后重启客户端（完全退出并重新打开 Claude Desktop；Claude Code 则重新连接）。查看当前版本：igpsport-mcp --version。

对于使用 uvx igpsport-mcp 一次性运行的用户，无需手动升级——uvx 默认使用最新版本。如果本地缓存了旧版本，请使用 uvx igpsport-mcp@latest，或先运行 uv cache clean 清除缓存。

卸载

1. 移除程序（两种系统的操作相同）：

uv tool uninstall igpsport-mcp

2. 移除本地凭据和缓存（可选，用于彻底清理）：

# macOS / Linux (Terminal)
rm -rf ~/.igpsport-mcp        # credentials (config.json)
rm -rf ~/.cache/igpsport-mcp  # tokens, SQLite, FIT file cache

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:USERPROFILE\.igpsport-mcp"
Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\igpsport-mcp"

3. 从客户端配置中移除 igpsport：Claude Desktop — 删除 claude_desktop_config.json 中 mcpServers 下的 igpsport 配置块；Claude Code — claude mcp remove igpsport；OpenClaw — openclaw mcp unset igpsport（或删除 ~/.openclaw/openclaw.json 中 mcp.servers 下的 igpsport 配置块）。

对于使用 uvx igpsport-mcp 一次性运行的用户，无需卸载“程序”——只需执行第 2 步和第 3 步。

提供的 17 个工具

活动与训练（9 个）

工具	用途
list_activities	列出活动（支持日期范围、分页）
get_activity_summary	单次活动的派生指标：NP / IF / TSS / 做功，以及心率与功率在各区间的时间
get_activity_streams	时间序列数据（强制降采样并选择通道，节省 Token）
get_activity_laps	圈 / 分段数据（每圈 NP）
get_athlete_profile	训练参数：FTP / LTHR（从 iGPSport 自动读取，也可通过环境变量覆盖）；体重和最大心率始终从 iGPSport 读取；包含区间边界
get_athlete_stats	按周期汇总的统计数据（根据活动列表在本地计算）
estimate_thresholds	根据近期骑行的均值最大曲线，为未进行正式测试的骑行者估算 FTP / LTHR（Coggan 20 分钟测试、临界功率交叉验证、Friel 心率实地测试）；每个数值都附有置信度、依据及“通过正式测试确认”的提示。只读——绝不写回，骑行者需手动应用估算结果
compare_activities	比较多项活动（2–5 项）
analyze_training_load	CTL / ATL / TSB 趋势与状态解读（杀手级查询）

路段（3 个）

工具	用途
list_segments_collected	列出已加星标的路段及你的最佳用时
get_segment_detail	路段详情：距离 / 坡度 / 爬升 + KOM + 最快排行榜 + 你的 PR
get_segment_rank	路段排行榜（query_type 1=总榜，2=年度榜等），包含你的排名

统计与成就（1 个）

工具	用途
get_member_statistics	官方年度统计与个人最佳：总距离 / 时长 / 卡路里 / TSS、月度距离、距离里程碑、各类 PR（最长距离 / 最长时长 / 最快速度 / 最大功率 / 最大爬升）

训练课程（4 个）——唯一的“写入”功能

工具	用途
create_workout	用自然语言描述结构化训练课程（热身 / 主训练组 / 间歇 / 冷身），将其编译为 iGPSport 原生格式，并推送到你的码表应用；支持 dry_run=true，可在不发送的情况下预览；with_calendar=true 还会返回标准 iCalendar（VEVENT）文件，供 Apple Calendar、Reminders 或 Notion 等下游工具使用
list_workouts	实时从服务端获取所有自定义训练课程（反映在应用中执行的删除操作）
get_workout_detail	获取指定训练课程的完整结构
delete_workout	删除训练课程。具有破坏性且不可撤销：默认显示确认预览；必须显式设置 confirm=true 才会实际删除

功率目标支持绝对瓦数、%FTP（使用你的 FTP 自动换算）和功率区间；也支持心率、踏频和速度目标。时长可按时间 / 距离 / 卡路里 / 手动圈按钮设置。创建的训练课程会显示在 iGPSport 应用的“训练课程”下，并可同步到你的码表以供执行。

派生指标参考

• NP（标准化功率）：((30 s rolling average power)^4 mean)^0.25；计算前会将数据流重采样至 1 Hz。
• IF = NP / FTP；TSS = duration_s × NP × IF / (FTP × 3600) × 100。
• CTL / ATL / TSB：每日 TSS 的指数加权移动平均（α = 1/42、1/7）；TSB = CTL − ATL。
• 无功率计备用方案：hrTSS = (duration_s / 3600) × (avg HR / LTHR)² × 100，并标注为 estimated from HR。
• 区间模型：心率使用 Friel 模型（基于 LTHR）；功率使用 Coggan 7 区模型（基于 FTP）。

常见问题

问：我需要功率计吗？ 答：不需要。没有功率计时，基于心率的指标仍可正常使用，TSS 会回退到 hrTSS（准确度较低，并会注明）。不过，建议设置 FTP 以解锁基于功率的指标。

问：我的数据会上传到其他地方吗？ 答：不会上传给任何第三方。除了读取和写入你自己的 iGPSport 账户数据（读取活动／统计数据，以及为你自己的训练课程执行 create_workout／delete_workout）之外，所有操作都在本地进行。FIT 文件和派生指标会缓存在本地。

问：create_workout／delete_workout 会弄乱我的数据吗？ 答：create_workout 只会添加新的训练课程——你可以使用 dry_run=true 预览编译结果，再决定是否发送。delete_workout 不可撤销，且默认会显示确认预览；要实际删除，必须明确设置 confirm=true——因此，未经你确认，LLM 无法删除课程。

问：with_calendar 会自动写入我的日历吗？ 答：不会。此服务只会生成标准的 iCalendar（VEVENT）文本内容；它不会调用任何日历 API，也不会向外部发送数据。是否将事件实际写入日历，取决于你的 LLM 客户端是否将其交给其他日历／提醒工具（例如 Apple Calendar、Reminders 或 Notion MCP）。由于训练课程是没有执行日期的模板，DTSTART 使用占位符 {{SCHEDULED_DATE}}——下游使用方会填入实际日期。

问：如果 API 出问题怎么办？ 答：iGPSport 可能会更改其 API，导致工具无法正常工作——届时工具会抛出明确的错误。请在 问题反馈 中报告问题。

问：支持跑步／其他码表吗？ 答：不支持。本项目专注于 iGPSport 骑行数据。

问：国际版有什么不同？ 答：国际版和中国服务器的账户彼此独立。国际版不支持路段功能（仍处于测试阶段，列表为空），并采用更简单的身份验证机制（不使用 WASM 签名）。活动、训练课程和统计数据的功能相同。详情请参阅“国际版支持”一节。

开发

uv sync --extra dev
uv run pytest            # tests
uv run pytest -m integration   # online integration tests
ruff check . && ruff format .  # lint / format

许可证

MIT。本项目与 iGPSport 没有任何关联。