Suunto MCP
Ask Claude anything about your training. Suunto MCP connects your Suunto watch data to Claude so you can just talk to your data instead of clicking through dashboards.
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y [email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add suunto-mcp -- npx -y suunto-mcp@1.1.0在終端機中執行。
{ "mcpServers": { "suunto-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
Built by a Suunto user who wanted to ask "how was my last long run?" and get a real answer with numbers — and to feed live training data into a personal AI coach.
🏃 For regular Suunto users: Suunto's API docs say access is for commercial partners only — that's not the full picture. Private users get access too. It just takes 3–4 weeks for approval after you apply. Submit, wait, enjoy. Don't let that disclaimer stop you. ✅
Once it's set up, just ask:
Claude figures out what data to pull. You just ask.
It's not just read-only either — Claude can push things to your watch too:
See What you can push to your watch below.
If you already have Claude Code, you don't need to run a single terminal command. Just open it and say:
"Please install and set up suunto-mcp from https://github.com/googlarz/suunto-mcp"
Claude Code will clone the repo, run all the install commands, and add everything to your Claude Desktop config — on its own. That's exactly how this project's author set it up: no manual terminal work.
Three things stay yours no matter what, by design, not because of missing tooling:
Claude will tell you exactly what to do and when for each of these.
If you want to do it manually, keep reading.
Before starting, make sure you have:
Once it's done, you never redo it.
Prefer one guided walkthrough with a pacing choice up front (fast path vs. explained-step-by-step) and a proper explanation of how syncing works? See GETTING_STARTED.md. What follows here is the same steps in reference form.
The setup has three parts:
Suunto has a free developer portal called apizone where you register apps that can access your data. You'll create an account, subscribe to the data plan, and register a small "app" — don't worry, there's nothing to build, it's just a name and a password you make up.
Go to apizone.suunto.com and sign up or sign in.
Use the same email you use for the Suunto app. If you have a Sports Tracker account, that works too — it's the same login system.
After signing in, follow the How to start guide — it walks you through subscribing to the Developer API. This is free and gives you access to your workout history.
Heads up: Suunto's website states that API access is only for commercial partners — ignore that. Private users do get access, it just takes 3–4 weeks for the subscription to be approved. Submit it and wait. It will come through.
You may see other products like "Sleep API", "Recovery API", "Daily Activity API". The Developer API is enough to get started (workouts). Subscribe to the other three as well if you want sleep, recovery, steps, the daily snapshot or the daily digest — they are listed next to the Developer API, and you can also add them later.
⏳ Stop here and wait. Once you've subscribed, Suunto needs to approve your request. This takes 3–4 weeks. You'll get an email when it's done. Come back to Steps 3–4 only after your subscription shows as Active in your apizone profile.
You're going to tell Suunto: "I have a small program, here's its name and a secret password — please let it read my data."
Go to your apizone profile page
Scroll down to OAuth application settings
Fill in the form:
Click Save
After saving, the form shows a Client ID — a long code that Suunto generated for you. Copy it.
What are these three things? — Client ID: your app's username, generated by Suunto — Client Secret: your app's password, chosen by you — Redirect URI: where Suunto sends you back after you approve access — must match exactly, typos break it
The Client Secret is never shown again after you save. If you forget it, just set a new one in the same form.
The subscription key is a second passcode that goes on every data request. Here's how to find it:
Save all three values before continuing — you'll need them in Part 2:
Used the "Let Claude Code install it" option above? Claude already ran every command below — skip to Part 3. These steps are for anyone doing it by hand.
Open Terminal on Mac (press ⌘Space and type "Terminal") or Command Prompt on Windows. Then run these commands one at a time:
git clone https://github.com/googlarz/suunto-mcp
cd suunto-mcp
npm install
npm run build
This downloads the code, installs what it needs, and builds it. Takes 1–2 minutes. If you see any errors, check the Troubleshooting section.
You'll create a file called .env in the suunto-mcp folder and put your three values in it. Even if Claude is doing the rest of this for you, type these three values in yourself rather than pasting them into the chat — keeps them out of your conversation history.
On Mac:
cp .env.example .env
open -e .env
This copies the template and opens it in TextEdit. Replace each placeholder with your actual values, then save and close.
On Windows:
copy .env.example .env
notepad .env
The file looks like this — replace the parts after the = signs:
SUUNTO_CLIENT_ID=your-client-id-here
SUUNTO_CLIENT_SECRET=your-client-secret-here
SUUNTO_SUBSCRIPTION_KEY=your-subscription-key-here
Save and close the file.
Only if you want to push guided workouts to your watch (see What you can push), add one more line:
SUUNTO_APP_NAME=your-app-name-here— it must exactly match the app name you registered on apizone.suunto.com in Step 3, or the watch will reject the upload. Not needed for anything else.
npm run auth
Here's exactly what happens:
① Terminal — you see a long URL printed and the message "Opening Suunto authorization in your browser…"
② Browser opens — Suunto's login page appears. It looks identical to the Suunto app login: email + password fields at the top, then "Sign in with Apple" and "Sign in with Facebook" below. Sign in with whichever you use.
③ Permissions screen — after logging in, a screen appears asking you to approve access for "suunto-mcp". It lists what the app will be able to read (your workouts). Click Authorize.
④ Browser confirmation — the page shows: "Suunto MCP connected. You can close this tab."
⑤ Terminal confirmation — prints: "Paired successfully. Tokens saved."
Done — you won't need to do this again. The connection stays active and renews itself automatically.
Browser didn't open automatically? Copy the long URL from the terminal and paste it into your browser manually.
npm run doctor
This runs a health check. You should see output like:
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
The exact lines vary a little, and more appear for the Sleep, Recovery and Daily Activity products. If any line shows ✗, the message tells you exactly what to fix — resolve it before moving on. A ! is only a warning (for example, an optional product you haven't subscribed to).
Used the "Let Claude Code install it" option? This part is done too — Claude edited your config directly. Restart Claude Desktop and jump to Step 11.
Now you'll tell Claude Desktop where to find Suunto MCP.
Open this file in a text editor (create it if it doesn't exist yet):
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonQuick way on Mac — run this in Terminal:
mkdir -p ~/Library/Application\ Support/Claude && open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json
Quick way on Windows — run this in Command Prompt:
notepad "%APPDATA%\Claude\claude_desktop_config.json"
(If it asks "file not found — create it?", click Yes.)
First, find the actual path to the suunto-mcp folder. In Terminal, while inside the folder, run:
pwd
It'll print something like /Users/yourname/suunto-mcp. Copy that.
Now paste the following into the config file. Replace /Users/yourname/suunto-mcp with the path you got from pwd, and replace the credential placeholders with your actual values.
If the file already has other servers configured, don't replace the whole file — just add the
"suunto"section alongside them. The structure must be valid JSON, so keep all the curly braces balanced. When in doubt, compare your file to the example below.If the file is empty, paste the whole block as-is.
{
"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"
}
}
}
}
To also push guided workouts to your watch, add one more line inside "env": put a comma at the end of the SUUNTO_SUBSCRIPTION_KEY line, then add "SUUNTO_APP_NAME": "your-app-name" (exactly the app name registered on apizone) on a new line after it. If you only ask Claude about your data, you don't need it.
Anything the server needs must be in this "env" block — a .env file is only read by the terminal commands (npm run auth, npm run doctor, the CLI) when you run them from this folder.
Save the file.
Three things, in order — this is the only part of setup nothing can do for you:
"What was my most recent workout?"
If Claude answers with your actual sport, date, and distance — you're done. If it doesn't, don't guess — go to Troubleshooting.
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.
To add sleep, recovery, or daily activity: go back to apizone.suunto.com, find each product, and subscribe. Then run npm run doctor to confirm they're active.
Suunto MCP isn't read-only. Claude can also send things back to your account:
Guided workouts show up as a SuuntoPlus Guide: exercise name and weight/reps on screen, lap button advances to the next one, a stopwatch (not a countdown) between exercises with a preview of what's next, a vibrate when a new exercise starts, and a "session complete" screen at the end. There's no live push to the watch itself — it appears after your phone's next normal Suunto app sync, same as any other watch data.
This pairs naturally with a coaching workflow: describe your goals, equipment, and current lifts to Claude, and it can write a real progressive program and push each session directly — see Pairs well with health-skill below for recovery-aware programming.
Ask Claude "generate my daily digest for yesterday" and it writes a color-coded markdown summary — steps, sleep, recovery balance, HRV, and a training-load model (Fitness/Fatigue/Form) — appended to SUUNTO_HISTORY.md in the folder the server runs from (set SUUNTO_DIGEST_HISTORY_PATH to choose another file).
Fitness (CTL), Fatigue (ATL), and Form (TSB) aren't Suunto API fields — there's no endpoint for them. They're computed here from each workout's real tss.trainingStressScore using standard 42-day/7-day exponential decay, the same math training-load tools like TrainingPeaks use. The running values persist in ~/.suunto-mcp/averages.json (override with SUUNTO_DIGEST_AVERAGES_PATH) since there's nowhere else to keep them.
How close is it to the watch? Checked on one day against the Suunto app: Fatigue matched (11), Form matched (2), Fitness came out about 1 lower (13.1 vs 14). Treat Fitness as ±1 of your watch; seed it from the app if you need it exact.
A few things worth knowing before you rely on it:
--seed-ctl 42 --seed-atl 38 on the CLI. Only works on the first-ever digest; ignored after that.CLI: suunto-mcp daily-digest 2026-04-20 [--seed-ctl 42 --seed-atl 38]. MCP tool: generate_daily_digest.
Always run npm run doctor first — it pinpoints most problems automatically.
Is this safe? Will Suunto lock my account? Suunto built this API specifically for people to connect their own tools — it's explicitly allowed. You're using it exactly as intended.
Is my data leaving my computer? Your data travels directly between your computer and Suunto's servers. Suunto MCP is just the bridge. When Claude asks about your workouts, it goes: Claude → Suunto MCP (on your machine) → Suunto's servers → back. No third-party services see your data.
Which Suunto watches work? Any watch that syncs to the Suunto app: Race, Vertical, 9 Peak Pro, 9 Peak, 5 Peak, Wing, Ocean, and older models. If it appears in your Suunto app, it works here.
Do I need to do anything when I record a new workout? No. Just ask Claude — it always pulls live data from Suunto.
What if I want to disconnect and stop using this? See Disconnecting below. You can fully revoke access in under a minute.
Can I use this with AI apps other than Claude? Yes — anything that supports MCP: Claude Code, Cursor, Windsurf, and others.
My Suunto app username is different from my email — which do I use? Use your email address to sign in to apizone. Your username will appear once you're authenticated.
~/.suunto-mcp/tokens.json — not uploaded anywhere.npx -y suunto-mcp fetches the newest version on a fresh start; if you pinned a version in args, change it. Restart Claude afterwards.git pull, npm install, npm run build, then restart Claude.See CHANGELOG.md for what changed.
Set these in the env block of your Claude config (or in .env for terminal commands).
To fully remove access:
rm -f ~/.suunto-mcp/tokens.json
If you used SUUNTO_TOKEN_STORAGE=keychain, delete the "suunto-mcp" entry in your system keychain instead. The daily digest also keeps ~/.suunto-mcp/averages.json and SUUNTO_HISTORY.md — delete them too if you want the health data gone."suunto" block from your Claude config and restart Claude.If you use googlarz/health-skill — a Claude skill for symptom triage and health Q&A — you can connect both to Claude: health-skill handles the health side while Claude reads your training, sleep, and recovery data from Suunto MCP in the same conversation. Together they can answer questions like "given my recovery scores this week, should I keep tomorrow's interval session?" with real numbers.
The same combination works for planning, not just Q&A: Claude can check your actual HRV and sleep before writing a session, scale it back on a bad recovery day instead of a generic one, and push the result straight to your watch with push_strength_guide (gym) or push_interval_guide (cardio). Ask for it directly — "check my recovery and plan today's gym session" — no extra setup beyond having both connected.
To also store your daily step counts in health-skill's own records, run suunto-mcp sync-to-health-skill --health-root <your health folder> (add --person-id for a household member). It copies steps only, and only for days that are finished — today's total is picked up tomorrow.
For the full version — real progressive-overload programming that persists week to week instead of a one-off ask — install googlarz/gym-skill: /gym setup once, then /gym plan//gym today//gym log//gym review going forward.
The package is published on npm as suunto-mcp, so you can skip Step 5 (no git clone, no build). You still need Node.js 20 or newer and the credentials from Part 1.
Pair your account (replaces Step 7). Run these in a terminal, with your own values:
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
The first command opens the browser pairing page and saves your tokens to ~/.suunto-mcp/tokens.json; the second checks that everything is connected.
Connect to Claude Desktop (replaces Step 10). Use npx instead of a path to the code:
{
"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"
}
}
}
}
The first start downloads the package, so it can take a few seconds. To stay on one version, write "suunto-mcp@<version>" in args (for example the current one from npm). In Claude Code: claude mcp add suunto -e SUUNTO_CLIENT_ID=... -e SUUNTO_CLIENT_SECRET=... -e SUUNTO_SUBSCRIPTION_KEY=... -- npx -y suunto-mcp.
Run this in a terminal (use your own values and the real path to this folder), then claude mcp list to verify it's loaded:
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
Add -e SUUNTO_APP_NAME=your-app-name if you want to push guided workouts.
After building, you can query Suunto data directly without Claude. From the cloned folder use node dist/index.js <command>; with the npm package use npx suunto-mcp <command> (or just suunto-mcp if installed globally):
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
Other commands: get-workout-fit, get-daily-activity, list-daily-activity, list-sleep, get-recovery, daily-digest, sync-to-health-skill. Run it with --help for the full list and every option. All output is JSON — pipe into jq for filtering.
npm run webhook
Starts an HTTP receiver on port 8422 that logs workout events as they arrive. It listens on 127.0.0.1 only, so expose it through a tunnel (cloudflared, ngrok) or a reverse proxy and register the URL in apizone → webhooks.
Set SUUNTO_WEBHOOK_SECRET to the notification secret you configure in apizone's OAuth application settings. Every request is verified against Suunto's X-HMAC-SHA256-Signature header and rejected with 401 if it doesn't match. Without the secret the receiver rejects everything (set SUUNTO_WEBHOOK_ALLOW_UNSIGNED=1 only for local testing). Other options: PORT, SUUNTO_WEBHOOK_HOST (default 127.0.0.1), SUUNTO_WEBHOOK_LOG (default ~/.suunto-mcp/webhooks.ndjson, written private and capped at 100 MB).
Most users can skip this whole section — asking Claude on demand is simpler.
To store your Suunto login tokens in your OS keychain (macOS Keychain, Windows Credential Manager) instead of a file:
SUUNTO_TOKEN_STORAGE=keychain npm install @napi-rs/keyring
SUUNTO_TOKEN_STORAGE=keychain npm run auth
Claude picks the right tool automatically — you don't need to know these. For the curious:
Workouts
24/7 health (requires individual product subscriptions on apizone)
Routes
Uploads & guided workouts (write — send data back to your account)
Other
fit-file-parser — FIT binary decodingMIT — use it, fork it, improve it.
MCP server that connects your Suunto watch data to Claude and other AI assistants.
{ "mcpServers": { "suunto-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Suunto 透過 stdio 在本機執行。
上次檢查時間:2026-11-16。 MCP server that connects your Suunto watch data to Claude and other AI assistants.