Suunto MCP

Suunto MCP

询问 Claude 任何有关训练的问题。 Suunto MCP 将 Suunto 手表数据连接到 Claude，让你只需与数据对话，而不必在仪表板中逐项点击。

本项目由一位 Suunto 用户打造。他想问“我上次的长跑表现如何？”，并得到包含具体数字的真实答案；还想将实时训练数据提供给个人 AI 教练。

🏃 面向普通 Suunto 用户： Suunto 的 API 文档称，只有商业合作伙伴才能访问——但实际情况并非如此。 个人用户也可以获得访问权限。申请后只需等待 3–4 周即可获批。提交申请，耐心等待，然后尽情使用。别让这段免责声明打消你的念头。✅

你可以做什么

设置完成后，只需提问：

• “我这个月跑了多少公里？”
• “比较我最近三次长跑——我的心率漂移有所改善吗？”
• “昨晚的健身训练中，我每组的心率表现如何？”
• “过去两周我的平均静息心率趋势如何？”
• “用教练报告的风格总结我的训练周。”
• “我最近状态不太好——我的恢复评分与上个月相比如何？”
• “找出所有平均心率超过 160 bpm 的锻炼。”
• “我今年哪次跑步的爬升最多？”

Claude 会判断该提取哪些数据。你只需提问。

它也不只是只读——Claude 还能将内容发送到你的手表：

• “规划今晚的健身训练并发送到我的手表。”
• “将昨天导出的 Garmin 数据上传为 Suunto 锻炼。”
• “将我最近的路线导出为 GPX，以便分享。”

请参阅下文的可以发送到手表的内容。

🤖 不想自己动手？让 Claude Code 帮你安装

如果你已经有 Claude Code，就不必运行任何终端命令。只需打开它并说：

“请从 https://github.com/googlarz/suunto-mcp 安装并设置 suunto-mcp。”

Claude Code 会自行克隆仓库、运行所有安装命令，并将所有内容添加到 Claude Desktop 配置中。本项目的作者正是这样完成设置的：无需手动操作终端。

有三件事无论如何都由你亲自完成，这是有意为之，并非工具功能不足：

1. 创建 apizone.suunto.com 账户——Claude 无法代你创建账户。
2. 填写 apizone 网页表单（为应用命名、查看订阅密钥）——这是你的账户会话；Claude 会准确告诉你该点击哪里，但无法代你点击。
3. 登录期间点击“Authorize”——这是 OAuth 按预期工作的表现。如果应用能批准自己的访问权限，就不安全了。

对于上述每一步，Claude 都会准确告诉你该做什么以及何时操作。

如果你想手动操作，请继续阅读。

你需要准备什么

开始之前，请确认你具备以下条件：

• 一块 Suunto 手表，已与 Suunto 应用同步（任何现代型号均可——Race、Vertical、9 Peak、5 Peak、Ocean 等）
• Claude Desktop（或其他兼容 MCP 的 AI 应用）
• Node.js——免费，在此下载，选择“LTS”版本
• Git——免费，在此下载
• 约 5 分钟提交申请 + 等待 Suunto 审批 3–4 周 + 约 15 分钟安装

完成后，无需再重新操作。

设置

想要先选择节奏（快速设置或逐步讲解），再按照引导完成整个流程，并了解同步的工作原理？ 请参阅 GETTING_STARTED.md。下面是相同步骤的参考版。

设置分为三个部分：

1. 在 Suunto 开发者门户注册 — 告知 Suunto 你的应用获准读取你的数据
2. 安装并配置 — 在你的电脑上运行软件
3. 连接到 Claude — 让 AI 查找并使用它

第 1 部分：在 Suunto 开发者门户注册（提交约需 5 分钟，然后等待 3–4 周）

Suunto 有一个免费的开发者门户，名为 apizone，你可以在其中注册可访问你数据的应用。你需要创建账户、订阅数据套餐，并注册一个小型“应用”——不用担心，你不需要构建任何东西，只需设置一个名称和一个自选密码。

步骤 1：创建 apizone 账户

前往 apizone.suunto.com 注册或登录。

请使用你登录 Suunto 应用时使用的邮箱。 如果你有 Sports Tracker 账户，也可以使用——它们使用相同的登录系统。

步骤 2：订阅 Developer API

登录后，按照 How to start 指南操作，其中会引导你订阅 Developer API。这是免费的，可让你访问自己的锻炼历史记录。

注意： Suunto 网站称 API 访问权限仅面向商业合作伙伴——请忽略这条说明。个人用户也能获得访问权限，只是订阅需要 3–4 周 才能获批。提交申请后耐心等待即可，最终会获批。

你可能会看到其他产品，例如“Sleep API”“Recovery API”“Daily Activity API”。入门只需订阅 Developer API（锻炼数据）。如果还想获取睡眠、恢复、步数、每日快照或每日摘要数据，也可以订阅另外三个产品——它们列在 Developer API 旁边，你也可以之后再添加。

⏳ 请在此暂停并等待。 订阅后，Suunto 需要批准你的申请。这需要 3–4 周。审批完成后，你会收到一封邮件。只有当 apizone 个人资料中的订阅状态显示为 Active 后，才继续执行步骤 3–4。

步骤 3：注册你的应用 （获批后再进行）

你需要告知 Suunto：“我有一个小程序，这是它的名称和一个秘密密码——请允许它读取我的数据。”

1. 前往你的 apizone 个人资料页

2. 向下滚动到 OAuth application settings

3. 填写表单：

   字段	填写内容
   App name	suunto-mcp（或你喜欢的名称）
   Client secret	自行设置一个独一无二的密码——只让你自己知道，例如用你自己的名字设置为 alice-suunto-2026。请记下来。不要使用这个示例值。
   Redirect URI	http://localhost:8421/callback — 请完全照抄

4. 点击 Save

保存后，表单会显示一个 Client ID——这是 Suunto 为你生成的一串长代码。请复制它。

这三项分别是什么？ — Client ID：应用的用户名，由 Suunto 生成 — Client Secret：应用的密码，由你自行设置 — Redirect URI：你批准访问权限后 Suunto 将你重定向到的位置——必须完全匹配，拼写错误会导致失败

保存后将无法再次查看 Client Secret。如果忘记了，只需在同一个表单中设置一个新密码。

第 4 步：获取订阅密钥 （批准后再执行）

订阅密钥是每次数据请求都要附带的第二个密码。查找方法如下：

1. 仍在 apizone 个人资料页面
2. 滚动到 Subscriptions 部分
3. 你的 Developer API 订阅会列在这里。旁边会显示 Primary Key——点击旁边的按钮即可显示密钥，然后复制。

继续之前，请保存好这三个值——在第 2 部分中会用到：

• Client ID（来自上面的 OAuth 应用表单）
• Client Secret（你设置的密码）
• Subscription Key（来自 Subscriptions 部分）

第 2 部分：安装和配置（约 10 分钟，需在 Suunto 批准后进行）

上面选择了“让 Claude Code 安装”选项？ Claude 已经运行了 下面的所有命令——请跳到第 3 部分。 以下步骤适用于手动操作的情况。

第 5 步：下载代码

在 Mac 上打开 Terminal（按 ⌘Space 并输入“Terminal”），或在 Windows 上打开 命令提示符。然后逐条运行以下命令：

git clone https://github.com/googlarz/suunto-mcp
cd suunto-mcp
npm install
npm run build

此操作会下载代码、安装所需内容并进行构建。需要 1–2 分钟。如果看到错误，请查看故障排除部分。

第 6 步：添加凭据

你需要在 suunto-mcp 文件夹中创建一个名为 .env 的文件，并将三个值填入其中。即使 Claude 会替你完成其余操作，也请亲自输入这三个值，不要将它们粘贴到聊天中——这样可以避免它们出现在对话记录里。

在 Mac 上：

cp .env.example .env
open -e .env

这会复制模板并在 TextEdit 中打开。将每个占位符替换为实际值，然后保存并关闭。

在 Windows 上：

copy .env.example .env
notepad .env

文件内容如下——替换 = 号后面的部分：

SUUNTO_CLIENT_ID=your-client-id-here
SUUNTO_CLIENT_SECRET=your-client-secret-here
SUUNTO_SUBSCRIPTION_KEY=your-subscription-key-here

保存并关闭文件。

仅当你想将引导式训练推送到手表时（参见可以推送到手表的内容），才需再添加一行：SUUNTO_APP_NAME=your-app-name-here——它必须与第 3 步中在 apizone.suunto.com 注册的应用名称完全一致，否则手表会拒绝上传。其他用途不需要此项。

第 7 步：关联你的 Suunto 账户

npm run auth

具体流程如下：

① Terminal——你会看到打印出来的一长串 URL，以及消息“正在浏览器中打开 Suunto 授权页面……”

② 浏览器打开——Suunto 登录页面会显示出来。它看起来与 Suunto 应用的登录页面完全相同：顶部是电子邮件和密码字段，下方是“使用 Apple 登录”和“使用 Facebook 登录”。使用你平时的登录方式即可。

③ 权限页面——登录后，会出现一个页面，要求你批准“suunto-mcp”的访问权限。页面会列出该应用可以读取的内容（你的训练记录）。点击 Authorize。

④ 浏览器确认——页面会显示：“Suunto MCP 已连接。你可以关闭此标签页。”

⑤ Terminal 确认——会打印：“关联成功。令牌已保存。”

完成——以后无需再次操作。连接会保持有效并自动续期。

**浏览器没有自动打开？**从终端复制那一长串 URL，并手动粘贴到浏览器中。

第 8 步：检查一切是否正常运行

npm run doctor

此操作会运行健康检查。你应该会看到类似以下内容的输出：

Suunto MCP — health check

  ✓  Node version             20.18.0 (require ≥ 20)
  ✓  Credentials              client_id, client_secret, subscription_key set
  ✓  Network → cloudapi-oauth.suunto.com   reachable (HTTP 200)
  ✓  Pairing                  paired (user: your-username), token expires in 47 min
  ✓  API probe (list_workouts)  received 1 workout

具体行内容会略有不同；如果启用了 Sleep、Recovery 和 Daily Activity 产品，还会显示更多内容。如果任何一行显示 ✗，消息会明确告知需要修复的内容——请先解决问题再继续。! 仅表示警告（例如，你尚未订阅某个可选产品）。

第 3 部分：连接到 Claude Desktop（约 5 分钟）

**选择了“让 Claude Code 安装”选项？**这部分也已完成—— Claude 已直接编辑你的配置。重启 Claude Desktop，然后跳到 第 11 步。

现在，你需要告诉 Claude Desktop 在哪里查找 Suunto MCP。

第 9 步：打开 Claude 配置文件

用文本编辑器打开此文件（如果文件尚不存在，请创建它）：

• Mac： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

Mac 快捷方式 — 在终端中运行：

mkdir -p ~/Library/Application\ Support/Claude && open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows 快捷方式 — 在命令提示符中运行：

notepad "%APPDATA%\Claude\claude_desktop_config.json"

（如果提示“找不到文件 — 要创建吗？”，请点击“是”。）

第 10 步：添加 Suunto MCP

首先，找到 suunto-mcp 文件夹的实际路径。在终端中进入该文件夹后，运行：

pwd

它会输出类似 /Users/yourname/suunto-mcp 的路径。复制该路径。

现在将以下内容粘贴到配置文件中。将 /Users/yourname/suunto-mcp 替换为你通过 pwd 获取的路径，并将凭据占位符替换为你的实际值。

如果文件中已配置了其他服务，不要替换整个文件 — 只需在其他服务旁边添加 "suunto" 部分。结构必须是有效的 JSON，因此请确保所有花括号都成对。在不确定时，请对照下方示例检查文件。

如果文件为空，请直接粘贴整个代码块。

{
  "mcpServers": {
    "suunto": {
      "command": "node",
      "args": ["/Users/yourname/suunto-mcp/dist/index.js"],
      "env": {
        "SUUNTO_CLIENT_ID": "your-client-id",
        "SUUNTO_CLIENT_SECRET": "your-client-secret",
        "SUUNTO_SUBSCRIPTION_KEY": "your-subscription-key"
      }
    }
  }
}

如需将指导训练也推送到手表，请在 "env" 中再添加一行：在 SUUNTO_SUBSCRIPTION_KEY 行末尾加上逗号，然后在下一行添加 "SUUNTO_APP_NAME": "your-app-name"（填写在 apizone 注册的准确应用名称）。如果你只让 Claude 查询数据，则不需要添加这一项。

服务所需的所有内容都必须放在这个 "env" 块中 — .env 文件只会在你从此文件夹运行终端命令（npm run auth、npm run doctor、CLI）时读取。

保存文件。

第 11 步：测试

按顺序完成以下三件事 — 这是设置过程中唯一无法代劳的部分：

1. 完全退出 Claude Desktop。 不只是关闭窗口 — Mac 上按 ⌘Q，或在 Windows 上右键点击任务栏图标 → 退出。 配置更改只有在重新启动后才会加载。
2. 重新打开 Claude Desktop。
3. 向它提问：

   “我最近一次训练是什么时候？”

如果 Claude 回答了你实际的运动类型、日期和距离 — 就完成了。 如果没有，请不要猜测 — 前往故障排除。

对话示例

You:    Compare my last three long runs. Has my heart-rate drift improved?

Claude: Looking up your workouts…
        Found 3 runs over 90 minutes in the last 6 weeks:
          • Apr 12 — 22.4 km, 2h09, avg HR 148, last-30min drift +6 bpm
          • Apr 19 — 24.0 km, 2h21, avg HR 144, last-30min drift +4 bpm
          • Apr 26 — 25.1 km, 2h28, avg HR 142, last-30min drift +2 bpm
        Drift is trending down despite slightly longer runs — your aerobic
        base is improving. Pace at the same HR is also ~3 s/km faster.

可用数据

如需添加睡眠、恢复或日常活动数据：返回 apizone.suunto.com，找到相应产品并订阅。然后运行 npm run doctor 确认订阅已启用。

你可以推送到手表的内容

Suunto MCP 不只是只读的。Claude 也可以将内容发送回你的账户：

引导式训练会以 SuuntoPlus Guide 的形式显示：屏幕上显示运动名称和重量／次数，按圈速按钮可进入下一个动作，动作之间显示秒表（而非倒计时）以及下一项预览，新动作开始时会振动，结束时会显示“训练完成”画面。不会实时推送到手表本身——它会在手机下次正常同步 Suunto 应用后显示，与其他手表数据相同。

这与教练工作流相得益彰：向 Claude 描述你的目标、器材和当前举重水平，它就能编写真正渐进式的训练计划，并将每次训练直接推送到手表——有关结合恢复情况制定训练计划，请参阅下方的与 health-skill 配合使用。

每日健康摘要

向 Claude 提出 "generate my daily digest for yesterday"，它就会生成一份带颜色标记的 Markdown 摘要——包括步数、睡眠、恢复平衡、HRV 和训练负荷模型（Fitness/Fatigue/Form）——并追加到服务运行目录中的 SUUNTO_HISTORY.md（设置 SUUNTO_DIGEST_HISTORY_PATH 可选择其他文件）。

Fitness (CTL)、Fatigue (ATL) 和 Form (TSB) 不是 Suunto API 字段——没有对应的 API 端点。这里会根据每次锻炼的实际 tss.trainingStressScore，使用标准的 42 天/7 天指数衰减计算这些指标，计算方法与 TrainingPeaks 等训练负荷工具相同。由于没有其他地方可以保存这些值，它们会持久化到 ~/.suunto-mcp/averages.json（可通过 SUUNTO_DIGEST_AVERAGES_PATH 覆盖）。

与手表的数值有多接近？ 我们曾选一天与 Suunto 应用进行核对：Fatigue 一致（11），Form 一致（2），Fitness 则低约 1（13.1 对 14）。Fitness 与手表显示值相差 ±1 都属正常；如果需要精确匹配，可用应用中的数值初始化。

使用前值得了解几点：

• CTL/ATL 首次使用时从 0 开始，需要 4–6 周才能接近合理数值——没有 API 可以读取手表自身显示的 Fitness/Fatigue。要跳过冷启动，请在生成第一份摘要时告诉 Claude 手表上的数值（"my watch shows Fitness 42, Fatigue 38, seed the digest with those"），或者在 CLI 中传入 --seed-ctl 42 --seed-atl 38。此参数仅在首次生成摘要时生效，之后会被忽略。
• TSB 颜色与手表自身的图例一致（🔵 最佳 >+10，🟢 平衡 0 至 +10，🟡 受影响 −10 至 0，🔴 紧张 <−10）——并非自行编造的标准。
• 爬升速率（本周 CTL 与 7 天前的对比）有自己的等级：🔴 高于 +8/周表示负荷增加过快——存在真实的受伤风险，而不只是“进步良好”。🟢 +3 至 +8 表示稳步提升，🟡 −2 至 +2 表示保持稳定，🟠 低于 −2 表示体能正在下降。
• 恢复平衡会分别报告晨间值（夜间的最低点）和峰值（当天的最高点）——由于峰值自然高于夜间低点，两者采用不同的颜色等级。
• **如果 HRV 连续 2 天以上低于正常范围，或晨间恢复值连续 2 天以上低于 65%，**摘要会添加一条建议检查血压的提示——HRV/恢复值持续偏低是真实的生理信号，值得通过另一项数据进一步确认。
• 滚动基线会分别跟踪每项指标，并为“派对之夜”（>20,000 步）单独设置一组数据，以免异常日影响正常日的平均值。
• **按时间顺序运行日期。**摘要拒绝处理早于或等于最近一次处理日期的日期，因此如果漏了一天，后续日期已经运行后就无法再补上——累计值会逐日递增。
• 这些部分需要在 apizone 订阅 Sleep 和 Recovery API 才能填充数据——即使没有订阅，摘要仍会生成，只是这些部分会显示“无数据”，而不会报错。

CLI：suunto-mcp daily-digest 2026-04-20 [--seed-ctl 42 --seed-atl 38]。MCP 工具：generate_daily_digest。

故障排除

请务必先运行 npm run doctor — 它会自动定位大多数问题。

常见问题

这样安全吗？Suunto 会锁定我的账户吗？ Suunto 专门构建了此 API，供用户连接自己的工具使用——这明确是允许的。你的使用方式完全符合预期。

我的数据会离开电脑吗？ 你的数据会直接在电脑和 Suunto 的服务器之间传输。Suunto MCP 只是桥梁。当 Claude 询问你的锻炼情况时，数据会经过：Claude → Suunto MCP（在你的电脑上）→ Suunto 的服务器 → 返回。没有第三方服务会看到你的数据。

哪些 Suunto 手表可以使用？ 任何能与 Suunto 应用同步的手表都可以：Race、Vertical、9 Peak Pro、9 Peak、5 Peak、Wing、Ocean 以及较早的型号。只要它显示在你的 Suunto 应用中，就能在这里使用。

记录新的锻炼后，我需要做什么吗？ 不需要。只要询问 Claude 即可——它始终会从 Suunto 获取实时数据。

如果我想断开连接并停止使用，该怎么办？ 请参阅下文的断开连接。不到一分钟即可完全撤销访问权限。

我可以将它与 Claude 以外的 AI 应用搭配使用吗？ 可以——任何支持 MCP 的应用都可以：Claude Code、Cursor、Windsurf 等。

我的 Suunto 应用用户名与邮箱不同——应该使用哪个？ 使用邮箱地址登录 apizone。通过身份验证后，你的用户名便会显示。

隐私

• 所有数据都在你的电脑和 Suunto 的服务器之间直接传输。没有第三方服务器，也没有分析功能。
• 你的登录凭据存储在本地的 ~/.suunto-mcp/tokens.json 中，不会上传到任何地方。
• Suunto 会在 apizone → profile → Authorized applications 中将你连接的应用显示为“suunto-mcp”。你可以随时在那里撤销访问权限。
• AI 只能看到它为回答你的问题而明确请求的数据，不会一次性看到你的全部历史记录。

升级

• npx： npx -y suunto-mcp 会在全新启动时获取最新版本；如果你在 args 中固定了版本，请更改它。之后重启 Claude。
• **克隆的文件夹：**运行 git pull、npm install、npm run build，然后重启 Claude。

请参阅 CHANGELOG.md 了解变更内容。

环境变量

在 Claude 配置的 env 区块中设置这些变量（或在终端命令使用的 .env 文件中设置）。

断开连接

要完全移除访问权限：

1. 登录 apizone.suunto.com → profile → Authorized applications → 移除 suunto-mcp。Suunto 会立即停止认可此连接。
2. 删除本地凭据：

   rm -f ~/.suunto-mcp/tokens.json
   

   如果你使用了 SUUNTO_TOKEN_STORAGE=keychain，请改为删除系统钥匙串中的“suunto-mcp”条目。每日摘要还会保留 ~/.suunto-mcp/averages.json 和 SUUNTO_HISTORY.md——如果你也想删除健康数据，请一并删除。
3. 从 Claude 配置中移除 "suunto" 区块，然后重启 Claude。

与 health-skill 搭配使用

如果你使用 googlarz/health-skill——一款用于症状分诊和健康问答的 Claude 技能——可以将它和 Suunto MCP 都连接到 Claude：health-skill 负责健康相关内容，Claude 则会在同一段对话中读取你来自 Suunto MCP 的训练、睡眠和恢复数据。两者结合后，就能用真实数据回答诸如 “考虑到我本周的恢复评分，明天还应该进行间歇训练吗？” 这样的问题。

同样的组合也适用于计划安排，而不仅仅是问答：Claude 可以在制定训练计划前查看你实际的 HRV 和睡眠情况，在恢复状况不佳的日子缩减训练量，而不是给出通用计划；还可以通过 push_strength_guide（健身房）或 push_interval_guide（有氧训练）直接将结果发送到你的手表。直接提出需求即可——“检查我的恢复情况并规划今天的健身房训练”——除了连接这两者之外，无需额外设置。

若要将每日步数也存入 health-skill 自己的记录中，请运行 suunto-mcp sync-to-health-skill --health-root <your health folder>（如果是家庭成员，请添加 --person-id）。此命令只会复制步数，而且只处理已经结束的日期——今天的总步数会在明天同步。

如果要使用完整版本——能够逐周持续记录、真正采用渐进超负荷的训练计划，而不是一次性请求——请安装 googlarz/gym-skill：先运行一次 /gym setup，之后就可以使用 /gym plan//gym today//gym log//gym review。

高级用法

export SUUNTO_CLIENT_ID=your-client-id SUUNTO_CLIENT_SECRET=your-client-secret SUUNTO_SUBSCRIPTION_KEY=your-subscription-key
npx -p suunto-mcp suunto-mcp-auth
npx -p suunto-mcp suunto-mcp-doctor

{
  "mcpServers": {
    "suunto": {
      "command": "npx",
      "args": ["-y", "suunto-mcp"],
      "env": {
        "SUUNTO_CLIENT_ID": "your-client-id",
        "SUUNTO_CLIENT_SECRET": "your-client-secret",
        "SUUNTO_SUBSCRIPTION_KEY": "your-subscription-key"
      }
    }
  }
}

claude mcp add suunto -e SUUNTO_CLIENT_ID=your-client-id -e SUUNTO_CLIENT_SECRET=your-client-secret -e SUUNTO_SUBSCRIPTION_KEY=your-subscription-key -- node /full/path/to/suunto-mcp/dist/index.js

node dist/index.js list-workouts --limit 10
node dist/index.js get-workout <workoutKey>
node dist/index.js get-workout-laps <workoutKey>
node dist/index.js get-daily-snapshot 2026-04-20
node dist/index.js get-daily-snapshot 2026-04-14 --to 2026-04-20
node dist/index.js get-sleep 2026-04-20
node dist/index.js list-recovery --from 2026-04-01 --to 2026-04-30

npm run webhook

大多数用户可以跳过整个部分——按需询问 Claude 更简单。

SUUNTO_TOKEN_STORAGE=keychain npm install @napi-rs/keyring
SUUNTO_TOKEN_STORAGE=keychain npm run auth

致谢

• Suunto APIzone — 感谢他们向所有人开放 API
• Model Context Protocol — 本项目采用的标准
• fit-file-parser — FIT 二进制解码

许可证

MIT——随意使用、分叉并改进。