Suunto MCP is an MCP (Model Context Protocol) server that connects Suunto watch data to Claude and other compatible AI assistants, allowing users to ask about training data directly in natural language without clicking through dashboards. The project was created by a Suunto user, with the goal of replacing manual queries with conversation and providing real-time training data for a personal AI coach.
Purpose: Connect Suunto watch data with AI, query training, activity, sleep, and recovery information through conversation, and support data analysis and training plan feedback.
Main capabilities:
- Read data: training records, time-series samples, FIT file decoding, GPX export, all-day activity, sleep, and recovery/HRV.
- Conversational queries: You can ask "How many kilometers did I run this month?" "Compare my last three long runs, has heart rate drift improved?" "What was the heart rate for each set in last week's fitness class?" "What is my resting heart rate trend over the past two weeks?" "Summarize my training week in the style of a coach's report" "How does my recovery score compare with last month?" "Find all workouts with an average heart rate over 160 bpm" "Which run this year had the most elevation gain?" etc.
- Write functions: Push guided workouts to the watch (in the form of SuuntoPlus Guide), upload Garmin export files as Suunto training, and export recent routes as GPX.
- Daily health summary: Generate a color-coded markdown summary, including steps, sleep, recovery balance, HRV, and the training load model (Fitness/Fatigue/Form), appended to SUUNTO_HISTORY.md.
- Training load calculation: Fitness (CTL), Fatigue (ATL), and Form (TSB) are not Suunto API fields, but are calculated based on each workout's tss.trainingStressScore using 42-day/7-day exponential decay, similar to TrainingPeaks. It starts from 0 on first use and requires 4–6 weeks to converge.
How to use:
- Before installation, prepare: a Suunto watch (already synced to the Suunto app, such as Race, Vertical, 9 Peak, 5 Peak, Ocean, etc.), Claude Desktop or another MCP-compatible AI application, Node.js (LTS version), and Git.
- Register for the Suunto developer portal: Visit apizone.suunto.com, register with the same email as your Suunto app, and subscribe to the Developer API (free, approval takes 3–4 weeks). You can additionally subscribe to the Sleep API, Recovery API, and Daily Activity API.
- Create an OAuth application: On the apizone profile page, enter the App name (e.g., suunto-mcp), set a custom Client Secret, and set the Redirect URI to http://localhost:8421/callback。保存后获取 Client ID.
- Get the Subscription Key: In the Subscriptions section, view the Primary Key under Developer API.
- Install and configure: Clone the repository, install dependencies, build, and create a .env file with the Client ID, Client Secret, and Subscription Key. If you need to push guided workouts, add SUUNTO_APP_NAME (it must exactly match the registered App name).
- Authorization: Run the authentication command. The terminal prints a URL, open it in the browser, log in to your Suunto account and authorize. The terminal displays "Paired successfully. Tokens saved." and the connection renews automatically.
- Connect Claude Desktop: Edit claude_desktop_config.json, add the suunto configuration in mcpServers, and fill in the path and credentials. Restart Claude Desktop and ask "What was my most recent workout?" to verify.
- Alternative: If Claude Code is already installed, you can directly say "Please install and set up suunto-mcp from https://github.com/googlarz/suunto-mcp”，它会自动完成克隆、安装和配置，但创建 apizone account, filling out the web form, and clicking authorization still need to be done manually by the user.
Use cases: Suunto users who want to use AI to query and analyze training data, generate weekly training reports or health summaries, push training plans to the watch, export routes as GPX, or provide a data source for an AI coach. Also suitable for users who need to import data from other platforms (such as Garmin) into Suunto.
Limitations:
- Suunto API access requires an application, with approval taking about 3–4 weeks; the official website says it is limited to commercial partners, but private users can also apply.
- Creating an account, filling out the apizone form, and clicking OAuth authorization must be done manually by the user.
- The training load model (CTL/ATL/TSB) is calculated locally, not native watch data; it starts from 0 the first time and needs 4–6 weeks to converge, and can be accelerated by telling it the watch-displayed values during the first summary or by using the CLI parameters --seed-ctl and --seed-atl.
- Pushing guided training to the watch is not real-time and will only appear after the phone next syncs with the Suunto app.
- The CTL/ATL/TSB in the summary may differ slightly from the values displayed on the watch (in the example, Fatigue and Form match, while Fitness is about 1 lower).
- Other products (sleep, recovery, daily activity) require an additional subscription and must be confirmed as activated with npm run doctor.
- No specific pricing, billing method, or platform compatibility list is provided; this information is not yet available.
