suunto-mcp

<p align="center">
  <img src="assets/logo.svg" alt="Suunto MCP" width="640"/>
</p>

# Suunto MCP

[![CI](https://github.com/googlarz/suunto-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/googlarz/suunto-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/suunto-mcp.svg)](https://www.npmjs.com/package/suunto-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![suunto-mcp MCP server](https://glama.ai/mcp/servers/googlarz/suunto-mcp/badges/score.svg)](https://glama.ai/mcp/servers/googlarz/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.

> *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. ✅

---

## What you can do

Once it's set up, just ask:

- *"How many kilometers did I run this month?"*
- *"Compare my last three long runs — has my heart-rate drift improved?"*
- *"How did my heart rate hold up set by set in last night's gym session?"*
- *"What's my average resting HR trend over the last two weeks?"*
- *"Summarize my training week in the style of a coaching report."*
- *"I've been feeling off — how do my recovery scores compare to last month?"*
- *"Find every workout where I averaged above 160 bpm."*
- *"Which of my runs this year had the most elevation?"*

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:

- *"Plan tonight's gym session and send it to my watch."*
- *"Upload yesterday's Garmin export as a Suunto workout."*
- *"Export my last route as GPX so I can share it."*

See [What you can push to your watch](#what-you-can-push-to-your-watch) below.

---

## 🤖 Don't want to do this yourself? Let Claude Code install it

If you already have [Claude Code](https://claude.ai/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:
1. **Creating the apizone.suunto.com account** — Claude can't create accounts on your behalf.
2. **The apizone web form** (naming your app, revealing your subscription key) — it's your account session; Claude tells you exactly where to click, but can't click there for you.
3. **Clicking "Authorize"** during login — that's OAuth working as intended. An app that could approve its own access wouldn't be secure.

Claude will tell you exactly what to do and when for each of these.

**If you want to do it manually, keep reading.**

---

## What you need

Before starting, make sure you have:

- [ ] **A Suunto watch** synced to the Suunto app (any modern model — Race, Vertical, 9 Peak, 5 Peak, Ocean, etc.)
- [ ] **Claude Desktop** (or another MCP-compatible AI app)
- [ ] **Node.js** — free, [download here](https://nodejs.org), choose the "LTS" version
- [ ] **Git** — free, [download here](https://git-scm.com/downloads)
- [ ] **~5 min to submit** + 3–4 week wait for Suunto approval + ~15 min to install

Once it's done, you never redo it.

---

## Setup

> **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](GETTING_STARTED.md). What follows here is the same
> steps in reference form.

The setup has three parts:

1. **Register with Suunto's developer portal** — tells Suunto your app is allowed to read your data
2. **Install and configure** — gets the software running on your computer
3. **Connect to Claude** — lets the AI find and use it

---

### Part 1: Register with Suunto's developer portal (~5 min to submit, then wait 3–4 weeks)

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.

#### Step 1: Create your apizone account

Go to [apizone.suunto.com](https://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.

#### Step 2: Subscribe to the Developer API

After signing in, follow the [How to start](https://apizone.suunto.com/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". Skip those for now — the Developer API is enough to get started. You can add the others later if you want sleep and recovery data in Claude.

---

> ⏳ **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.

---

#### Step 3: Register your app *(do this after approval)*

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."

1. Go to your [apizone profile page](https://apizone.suunto.com/profile)
2. Scroll down to **OAuth application settings**
3. Fill in the form:

   | Field | What to enter |
   |-------|--------------|
   | **App name** | `suunto-mcp` (or anything you like) |
   | **Client secret** | Make up a unique password — something only you'd know, e.g. `alice-suunto-2026` with your own name. Write it down. Don't use this exact example. |
   | **Redirect URI** | `http://localhost:8421/callback` — copy this **exactly** |

4. 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.

#### Step 4: Get your subscription key *(do this after approval)*

The subscription key is a second passcode that goes on every data request. Here's how to find it:

1. Still on the [apizone profile page](https://apizone.suunto.com/profile)
2. Scroll to the **Subscriptions** section
3. Your Developer API subscription is listed there. Next to it you'll see a **Primary Key** — click the button next to it to reveal it, then copy the key.

**Save all three values** before continuing — you'll need them in Part 2:
- Client ID (from the OAuth app form above)
- Client Secret (the password you made up)
- Subscription Key (from the Subscriptions section)

---

### Part 2: Install and configure (~10 min, after Suunto approves you)

> **Used the "Let Claude Code install it" option above?** Claude already ran
> every command below — skip to [Part 3](#part-3-connect-to-claude-desktop-5-min).
> These steps are for anyone doing it by hand.

#### Step 5: Download the code

Open **Terminal** on Mac (press ⌘Space and type "Terminal") or **Command Prompt** on Windows. Then run these commands one at a time:

```bash
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](#troubleshooting) section.

#### Step 6: Add your credentials

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:**
```bash
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:**
```bash
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](#what-you-can-push-to-your-watch)), 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.

#### Step 7: Pair your Suunto account

```bash
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