Syncs Garmin Connect data to provide AI-driven running coaching, readiness verdicts, and workout planning via Claude.
Also known as edxleon/runspector, runspector
- Stars
- 11
- Tools
- 18
- Downloads, 30 days
- 938
- Latest version
- 0.10.0
- Last commit
- Nov 15, 2026
- License
- MIT
What is Runspector MCP?
Runspector syncs Garmin Connect data to provide AI-driven running coaching, readiness verdicts, and workout planning via Claude. It exposes 18 tools, such as get_athlete_profile, get_coaching_reference, get_training_readiness.
Summary generated from the project's README
About Runspector MCP server
Runspector is an open-source running coach designed for Garmin users who want to turn their biometric data into actionable training plans. It syncs information from Garmin Connect, including heart rate variability, sleep, Body Battery, and training load, into a local SQLite database on your computer. This approach ensures your data stays private without requiring a cloud backend or additional API keys.
Users can interact with their data through a local web application or by using the tool as an MCP server within Claude Desktop or Claude Code. When used with Claude, the system provides coaching cards and conversational assistance to explain training decisions. The server includes 18 specific tools that allow an AI client to check readiness, review recent runs, analyze intensity distribution, and even propose or undo workouts directly on your Garmin watch. While the readiness engine uses deterministic code to decide whether to go hard, keep it easy, or rest, the AI provides the natural language explanations for these verdicts.
What you can do with it
- 1Daily training readiness checksAsk the AI whether you should perform a hard workout, an easy run, or take a rest day based on your current recovery metrics.
- 2Biometric trend analysisUse the AI to examine your VO2max history or training load to understand your fitness progress over time.
- 3Injury and illness managementInform the coach that you are feeling unwell to trigger a check-in and adjust your training load accordingly.
Written from the project's README. Every use case is checked against a quote from it.
How to install Runspector MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Runspector MCP in Claude Code
$ claude mcp add runspector -- uvx runspector mcpInstall Runspector MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"runspector": {
"command": "uvx",
"args": [
"runspector",
"mcp"
]
}
}
}Install Runspector MCP in VS Code
.vscode/mcp.json
{
"servers": {
"runspector": {
"type": "stdio",
"command": "uvx",
"args": [
"runspector",
"mcp"
]
}
}
}Install Runspector MCP in VS Code CLI
$ code --add-mcp '{"name":"runspector","type":"stdio","command":"uvx","args":["runspector","mcp"]}'Install Runspector MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"runspector": {
"command": "uvx",
"args": [
"runspector",
"mcp"
]
}
}
}Install Runspector MCP in Codex
$ codex mcp add runspector -- uvx runspector mcpInstall Runspector MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.runspector] command = "uvx" args = ["runspector", "mcp"]
Install Runspector MCP in Gemini CLI
$ gemini mcp add -s user runspector uvx -- runspector mcpInstall Runspector MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"runspector": {
"command": "uvx",
"args": [
"runspector",
"mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for runspector 0.10.0 in an isolated container with no network and no keys. It answered and listed 18 tools.
Runspector MCP tools 18
Read from the server with tools/listget_athlete_profileWhat the app has learned about THIS athlete from their own data, each with its evidence: how many days they run and on which weekdays, their long-run day, a weekly other sport, how consistent they are, their intensity pattern over 28 days, the VO2max trend and whether a measurement is due, Garmin's load focus, resting-HR baseline and zones - and, where a value moved and held, since when. Call it once per conversation after `get_coaching_reference`, and use it to make the advice theirs. It is context, not today's numbers: those come from the other tools, and the decision stays the app's. Read-only; no Garmin call.
get_coaching_referenceThe coach's full rule set: how to read the data, today's decision, the planning rules, zones and intensity distribution, the energy boundary and the sources behind each threshold - the same text the app's own coach works from. Call it ONCE per conversation, before the first training advice, and follow it. No arguments, no Garmin call; it reads nothing of the athlete.
get_training_readinessToday's readiness verdict GO / EASY / REST with the signals behind it (HRV status, sleep score, Body Battery, resting HR vs 27-day baseline, ACWR, days since the last hard workout). Rule-based and conservative. START HERE for "should I train today?". Carries the app's own decision for today and, on a hard day, WHICH hard session the history calls for (VO2max intervals, threshold reps, or the steady block Garmin measures VO2max from) - explain that, do not pick another; the athlete's goal from their profile when set; the Garmin calendar for the next 14 days, each entry with its weekday, date and schedule id (what propose_change names). Flags stale data explicitly. When the last Garmin sync is older than 30 minutes it syncs first (10-40 s) and says so on top.
get_recovery_summaryAverages of sleep, HRV, resting HR, stress, Body Battery and steps over the last N days plus a snapshot of the latest day. Use for "how has my recovery been?". Aggregates only — never a day-by-day list.
get_daily_metricsEvery recorded recovery value for ONE day (default: latest day with data). Use when a single night/day is in question, not for trends.
get_trendWeekly averages of ONE recovery metric over the last N days — for "is my HRV / resting HR / sleep trending up or down?".
get_training_loadTraining-load picture: ACWR with its SOURCE (Garmin's EWMA ratio, or a self-computed fallback that is less reliable), Garmin training status, VO2max with change, and weekly load buckets. VO2max change is only reported when the value actually varied (Garmin carries the last value forward).
get_recent_activitiesWorkout digest: totals per sport plus the latest workouts, each run classified Quality / Long Run / Easy (from training effect and duration). Use to see what was actually trained before recommending the next session.
get_intensity_distributionTime in heart-rate zones across all runs (easy Z1-2 / moderate Z3 / hard Z4-5 / Z5) with percentages — the basis for the 80/20 polarisation question. States how many runs have zone detail, so an incomplete picture is visible.
analyze_workoutDeep dive into ONE run: time in each HR zone, interval structure (rep count, rep length, work vs recovery HR), weather, performance condition, plus rule-based notes. Default: the latest run with detail. The interval structure is Garmin's auto-detection — if the athlete states a different structure, the athlete is right.
get_vo2max_historyVO2max over the last 8 weeks as STEPS (only the days the value really changed — Garmin carries it forward in between) plus a descriptive comparison of the last 28 days with the 28 before (distance, Z5 minutes, easy share, temperature). Use for "why is my VO2max moving?". Descriptive, not causal.
sync_garminPull the latest days and workouts from Garmin Connect NOW. Call this first when today's run or last night's sleep is missing. Takes 10-40 s. Read-only towards Garmin; writes only to the local database.
Show all 18 toolsShow fewer tools
propose_workoutBuild a structured session for the athlete's route or time budget and file it as a PROPOSAL - warm-up, work reps with targets, recovery jogs, cool-down - sized so the whole thing adds up to the route. Targets come from the athlete's own Garmin zones; anything not measured is listed as an assumption. Use when the athlete asks for a workout ("plan me intervals for my 10 km", "an easy 45 minutes", "a threshold session") or when the readiness verdict calls for a different session than the one on the calendar. Kinds: easy/long (one capped step), threshold (Z4 reps), vo2max (Z5 reps), steady (>= 12 min even effort at threshold - the only shape Garmin measures VO2max from). `day` defaults to today. Returns the preview and a proposal id. NOTHING is written to Garmin: show the preview, and only if the athlete says yes call apply_workout with the id. On an impossible request (route too short) returns why, not a session.
propose_weekBuild a polarised training week and file it as ONE proposal: a VO2max session and a threshold session 48 h apart, the long run on its weekday, easy runs between, nothing hard the day before or after the long run, at least one rest day. The sessions go on the days the athlete usually runs, and the quality sessions keep clear of a weekly other sport - read from their history, each an `assumption:` line. Sized from the athlete's own running weeks and read against their history, in code: +10 % by default, held or unloaded on the load ratio, a down week after three weeks up, a return week after a pause, and a measurement week (a steady block in the threshold slot) when VO2max has had no new value for 28 days - each one an `assumption:` line in the preview; explain the line, do not override it. Targets from their own zones, pace from Garmin's race predictions when no threshold is measured. Use when the athlete asks for their week ("plan my week", "what should next week look like"). The calendar wins: a day that already has an entry gets nothing, and a quality session too close to a hard calendar day becomes an easy run - each change is a `calendar:` line. Returns every session with its day and one proposal id; apply_workout with that id puts the package on Garmin after the athlete's yes. Nothing is written here.
propose_changeFile the athlete's OWN change to their planned week as a proposal: "Friday instead of Saturday", "Tuesday shorter", "no intervals this week", "add an easy run on Thursday". The athlete decides: the change is kept as asked even where the rules disagree - more than the plan's step, two hard days in a row, a hard session in a return week, a run on a rest day or while they said they are in pain. What the rules think of it comes back as `coach:` lines; say them to the athlete in your own words, and suggest a better change in your answer instead of making one they did not ask for. A workout this app did not make can be removed or replaced, not moved. Returns the change with its days and a proposal id. NOTHING is written to Garmin: apply_workout with the id after the athlete's yes; undo_workout takes it back.
apply_workoutWRITE a proposed session to the athlete's Garmin account: upload the workout, schedule it on the proposal's day, push it to the watch, then read it back and verify structure and targets. Call ONLY after the athlete has seen the preview and explicitly agreed - a request ("plan me 10 km") is not agreement, "yes, put it on the watch" is. Not available to the app's own card runs; there the athlete clicks. Returns what is now on Garmin, with any warning (not pushed because the watch is offline; a mismatch found on read-back). A proposal can be applied once; an unknown or used id says so and lists the open ones.
undo_workoutTake a session (or a whole applied week) back OFF the athlete's Garmin calendar. The counterpart of apply_workout: use it when the athlete says the session should not be there after all, or after trying the write path out. It unschedules - the workout stays in their Garmin library, so applying the same proposal again puts it back on a day without building or uploading anything a second time. Only sessions this app uploaded and scheduled are touched; a calendar entry that has changed hands since is left alone and reported. Like apply_workout it needs the athlete's explicit yes, and it is not available to the app's own card runs.
check_inRecord what the athlete SAYS about themselves today: ill, in pain, sore or stressed - or that it is over. Call it when they tell you, in their own words ("I have a cold", "my calf hurts", "legs are heavy from Sunday", "rough week at work"); never from the data alone - a low HRV is not a cold. It changes today's decision in code: ill or pain rest the day whatever the watch says, and after they end it, as many easy days follow as it lasted; sore or stressed take the hard session away. It holds until they say it is over, or runs out after a few days without a new word; saying it again keeps it open. Returns what was recorded and the app's decision for today now. Local only, nothing goes to Garmin; not available to the app's own card runs.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableedxleon/runspector is public and reachablegithub.com/edxleon/runspector ↗Pass
- Package names this repository as its sourcerunspector names edxleon/runspector as sourcepypi.org/project/runspector/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for runspectorpypi.org/project/runspector/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/edxleon/runspector ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from runspectorPass
- No critical advisory in the package or its dependencies36 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubRunspector — AI running coach for Garmin
A free, open-source AI running coach for Garmin watches. Runspector syncs your Garmin Connect data - HRV, sleep, Body Battery, resting heart rate, training load and every run - into a file on your own computer, decides each day whether to go hard, keep it easy or rest, and lets Claude explain why and plan your week: in a small local web app, or as a Garmin MCP server in Claude Code and Claude Desktop. No cloud, no API key needed - your own Claude Code sign-in is enough.
https://github.com/user-attachments/assets/0b4d7d86-5ab7-439b-82cb-89a004b71405
The 90-second demo, with voice-over: the synthetic demo athlete, rebuilt from this repo by scripts/video.py (file). No player above? The GitHub mobile app shows no videos: ▶ play the demo in the browser.
The built-in synthetic athlete (runspector serve --demo). Every image is regenerated by
python scripts/screenshots.py, and the coach card is an unedited agent run against that same
demo database, kept in demo-card.json so the picture cannot
drift from the app — the decision it explains (EASY, a day after a hard session) is the one on the Today tab
beside it. docs/screenshots/ has each of the five tabs full-length, in both
themes — e.g. today.png and
today-light.png.
I came to running late, and for a long time my VO2max would not move. I had always trained a lot, and it had never really shown up in that number — so I assumed more of the same would eventually work. It did not. I was training wrong, in ways the watch on my wrist had the data to show me and never did: Garmin collects everything and explains nothing.
That was the idea. The data is already there; let an AI read it and coach — with the training aimed squarely at raising VO2max rather than at collecting kilometres, and with the decision rules written down so the coach explains them instead of improvising. This repository started as that tool for one athlete. It is now installable for anyone with a Garmin watch and Claude Code (a Claude plan is enough).
No cloud backend, no API key needed, no Docker. One Python package that syncs your Garmin data into a SQLite file on your machine, shows it in a small web app, and lets Claude act as your coach — with a deterministic readiness engine underneath, so the AI explains decisions instead of inventing them.
If you came for the engineering rather than the running, the five decisions this repository is
actually about — each with the measurement behind it — are in
Design decisions. The short version: the verdict is
pure code and only the explanation is AI · the agent runs on
an allowlist, not a denylist (--tools "", one MCP server, empty temp cwd) ·
prompts are regression-tested by an LLM-as-judge suite whose last run is
in the repo · quantities that exist in two languages are pinned by
executing the shipped JavaScript against the Python · and the
release gate scans binaries too, with a false-positive counter-case. CI runs lint,
1674 tests, 151 frontend tests and that gate on three operating systems and two Python versions, with every
action pinned to a commit SHA — and a second job that builds the wheel, installs it as a user would and
drives the installed executable through this quick start on all three systems,
because the suite proves the code and only an install proves the package.
Formerly runcoach-ai: same project, renamed in v0.5.0. Old links redirect here. Coming from it: three steps to switch over, and your data moves by itself.
Not affiliated with Garmin. Uses the unofficial python-garminconnect library against your own account. This is a training tool, not medical advice.
Quick start
# 1. install (needs uv: https://docs.astral.sh/uv/)
uv tool install runspector
# without uv: pipx install runspector
# 2. look around without any account
runspector serve --demo
# 3. the real thing
runspector serve # first start: checks Garmin and Claude, opens http://127.0.0.1:8765 -
# sign in to Garmin right there (Setup → Sign in to Garmin; only a
# session token is stored) - and syncs the last 30 days in the background
Garmin is signed into on the page itself (Setup → Sign in to Garmin, or Sign in again when the
session has expired): e-mail, password and Garmin's code if your account uses one, and the sync starts
right after. runspector login does the same from any terminal, and a running app picks it up on ↻ - no
restart. Claude is only needed for the coach cards: see Connecting Claude.
runspector doctor tells you what is missing — it checks the Garmin session by actually
using it, and reports the data age, because a token that quietly expired is how this kind of app dies.
Use runspector doctor --offline to skip the Garmin call. Exit 1 means something needs fixing, so
runspector doctor || notify-me works in a cron; a missing Claude CLI is reported but does not set it,
since everything except the coach cards works without it.
Garmin MCP server for Claude Code and Claude Desktop
The same data, and the same rules, as an MCP server with 18 tools - among them today's readiness verdict, recovery, training load, recent runs, intensity distribution, the VO2max history, what the coach has learned about you, a Garmin sync, a check-in when you say you are ill or hurt - and propose, change, apply and undo for the workouts on your watch.
claude mcp add runspector -- runspector mcp
# then just ask: "should I train today?"
# or: "plan me an easy 40 minutes for tomorrow" - you see the session, and it goes
# on your watch only after you say yes ("take it back off" undoes it)
In Claude Desktop, or any MCP client with a JSON configuration (sign in once first: runspector login):
{ "mcpServers": { "runspector": { "command": "uvx", "args": ["runspector", "mcp"] } } }
Keep it fresh without the app (cron / Task Scheduler): runspector sync. For the morning:
runspector today --sync prints today's call in a few lines - GO / EASY / REST with its sentence, the
signals behind it, today's planned session with its easier option - and exits 3 when there is nothing
from today yet, so a cron and any notifier can tell "not synced" from "rest day".
Later on:
uv tool upgrade runspector # the newest release; your data and Garmin session stay where they are
uv tool uninstall runspector # removes the program only - delete ~/.runspector yourself if you want the data gone
uv tool install runspector takes the latest release from PyPI (runspector==0.10.0 pins one; pipx install runspector
and pipx upgrade runspector do the same without uv);
uv tool install git+https://github.com/edxleon/runspector takes whatever is on main.
Connecting Claude
runspector does not connect to Claude itself and never asks for a Claude password or key. The coach runs on Claude software you sign into with your own account, through Anthropic's own sign-in.
| What you want | What you need |
|---|---|
| Today's verdict and its reasons, your runs, the trends, the sync | nothing from Claude |
| The coach cards in the web app (Ask the coach, Should I train today?, Analyze this run, Review my week) and the sessions they put on your watch | Claude Code on this computer, signed in |
| Coaching in a chat instead, sessions on your watch included | Claude Desktop or Claude Code, with runspector added as an MCP server |
What "a Claude plan" means. Claude Code needs a paid Claude subscription from claude.com/pricing - Pro, Max, Team or Enterprise - or an Anthropic Console (API) account, which is billed per use. The free Claude plan does not include Claude Code. On a plan, the coach cards count against that plan's usage like any other Claude Code use: there is no key to create and no bill per card. runspector itself is free.
With Claude Code (needed for the coach cards)
Claude Code is Anthropic's command-line tool. You only install it and sign in once; runspector starts it in the background for each card.
# 1. install - macOS / Linux (Windows PowerShell: irm https://claude.ai/install.ps1 | iex)
curl -fsSL https://claude.ai/install.sh | bash # or: brew install --cask claude-code
# 2. sign in - opens your browser, sign in with your Claude account
claude auth login
# 3. check
runspector doctor # "Claude: signed in with your Claude subscription"
More install options (WinGet, npm, Linux packages): Claude Code setup.
If Claude Code was missing when you started runspector serve, reload the page afterwards - no restart.
If your Claude Code is signed in with a Console API key or a cloud provider (Bedrock, Vertex) instead of a
plan, the cards run on that and are billed there; the setup check says so. An ANTHROPIC_API_KEY that is
only exported in your shell, for other work, is removed from the card runs unless you set
RUNSPECTOR_ALLOW_API_KEY=1.
With Claude Desktop only (no command-line tool for Claude)
If you use the Claude desktop app (claude.ai/download), you can coach in its chat without Claude Code:
- Install runspector and sign in to Garmin once (
runspector login, or the page ofrunspector serve). - In Claude Desktop: the Claude menu → Settings… → Developer → Edit Config, and add:
(the file is{ "mcpServers": { "runspector": { "command": "runspector", "args": ["mcp"] } } }~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS,%APPDATA%\Claude\claude_desktop_config.jsonon Windows; keep any servers already in it). - Quit and restart Claude Desktop, then ask: "should I train today?"
If the server does not show up, Claude Desktop may not find the command: put the full path from
which runspector (Windows: where runspector) into "command". The web app's coach cards still need
Claude Code; in Desktop the same coaching happens in the chat.
Without Claude
The readiness verdict and its reasons, the runs, the trends and the sync all work. What needs Claude is everything the coach writes: the cards, and the sessions it proposes for your watch.
Questions people ask
Does Garmin have an AI coach?
Garmin offers three kinds of coaching of its own. Garmin Coach is a set of free adaptive training plans in Garmin Connect for a 5K, 10K or half marathon, which adapt to the runs you log. Many watches show daily suggested workouts, built from your activities once the watch has a training status and a VO2max estimate. Garmin Connect+, a paid subscription since March 2025, adds Active Intelligence: AI-powered insights and suggestions through the day, launched in beta; everything that was in Garmin Connect before stays free. Runspector reads the same Garmin data and is a different kind of tool: it decides today with every reason written out by rules you can read, lets you ask a coach in your own words, and plans sessions that go on your watch only after your yes - on your own computer.
Is there a free AI running coach for Garmin?
Runspector is free and open source (MIT). It installs from PyPI and keeps your data on your own computer. Today's verdict, your runs, the trends and the sync need nothing but your Garmin account. The coach itself runs on Claude, through Claude Code or Claude Desktop with your own Claude account; Connecting Claude says which plan that needs. Garmin's own Garmin Coach plans are free as well.
Which Garmin watches work?
Any Garmin watch that syncs to Garmin Connect gives runspector your runs. Today's verdict reads four recovery signals - HRV status, sleep score, Body Battery and your resting heart rate against your own baseline - plus your training load. A watch that records no HRV status overnight still gets a verdict from the others, but a GO that rests on fewer than two signals becomes EASY: thin data is no green light. To put sessions on the watch, it has to run structured workouts from Garmin Connect, with heart-rate or pace targets. Current Forerunner, fenix, epix, Venu and Instinct models are examples; whether a model records HRV status or Body Battery, its specifications on Garmin's site say.
How do I connect my Garmin data to Claude?
Install runspector, sign in to Garmin once (runspector login, or the button on the page), and either
open the app (runspector serve) or add it to Claude Code as an MCP server:
claude mcp add runspector -- runspector mcp. Then ask "should I train today?". See
the MCP server for Claude Desktop.
Do I need a Garmin developer account or an API key?
No. runspector signs in with your own Garmin account, through a community library - see Can Garmin block my account? below. On the Claude side no API key is needed either: a Claude plan and Claude Code are enough.
Does it work with Apple Watch, Coros, Polar or Strava?
No - Garmin only. Every number comes from Garmin Connect, including Garmin's own readings (HRV status, Body Battery, training load, VO2max), and the workouts it plans go back onto a Garmin watch.
Is my Garmin password stored?
No. It goes to Garmin once, to sign in. Garmin answers with a
session token, and only that is kept, on your computer, in a folder only your user account can read.
The page's sign-in takes the password only on the computer runspector runs on: opened from a phone,
the page is plain HTTP across your network, so there it points to runspector login instead.
Does it cost anything extra?
runspector is free (MIT). Coach cards use your Claude plan the way any Claude Code use does, with no API key and no bill per card. Without Claude, everything except the cards still works.
What does Claude see?
The numbers this app shows (readiness, recent runs, zones, weekly load), and only when you start a card or ask in Claude Code. It never sees your Garmin password, the session token or any raw file. It reaches Claude through your own account, under your plan's terms. And you can see it too: under every card, How this card was made lists everything the coach looked at and checks each number on the card against it; the You tab lists what chats in Claude read. What you mention about yourself while asking on a card - your time on weekdays, your goal, an old injury - the coach notes for later, each fact checked against what you wrote before it is kept, and never without saying so; the You tab lists each with the question it came from and lets it go.
Can it mess up my watch or my calendar?
Reading is all it does on its own. Something goes to Garmin only when you press "Put on watch" or say yes in Claude Code, and then only the session shown to you. "Take off watch" removes it again. The coach's own card runs cannot write at all.
Can Garmin block my account?
runspector signs in through python-garminconnect, a community library that Garmin does not officially support. A daily sync makes about 25-40 requests and the first one (a month of data) a few hundred. It pauses between workout downloads, never fetches more than 90 days, and stops at the first rate-limit answer instead of retrying into it. That is no guarantee, but it is not scraping either.
Is this medical advice?
No. It is a training tool. Pain, dizziness or anything that feels wrong goes to a doctor, and the coach says so instead of planning around it.
How do I remove everything?
Delete ~/.runspector (the app's footer shows the folder) and run
uv tool uninstall runspector. To cut the token off at Garmin as well, change your Garmin password.
What you get
| Tab | What it answers |
|---|---|
| Today | GO / EASY / REST with the signals behind it, one decision sentence for today and, on a hard day, which hard session (VO2max intervals, threshold reps, or the steady block Garmin measures VO2max from), Garmin's own Training Readiness beside it on watches that have one (its opinion - the call is the app's), four buttons for what the watch cannot see - ill, pain, sore legs, stressed - that change the call (ill or pain rest the day, and as many easy days follow as it lasted), your VO2max with the days since it last really changed, this week planned vs. done - tap a day to see what a session is (length, distance, pace, its steps) and change it: move it, make it shorter, longer or another kind, take it out, add a run, or tell the coach in your own words; the coach says what it thinks of the change, you decide, and it reaches the watch with "Put on watch" and comes off again with an undo -, last night's sleep, your zone bounds with their origin. Coming back to the page after a while syncs first |
| Runs | Every run with its intensity band, real interval structure (5×4′, not "5 minutes"), zones, weather, performance condition — and an Analyze this run button |
| Trend | VO2max as honest steps (and whether a measurement is due) with your body weight beside it - VO2max is per kilogram, so the page says how much of a change the weight alone explains -, lactate threshold history, weekly hard-minute share vs. an 80/20 target, aerobic efficiency (pace at a fixed heart rate) with spread and trend, volume, polarisation, ACWR and monotony (how alike the last seven days were - an even, heavy week holds the next one), and Garmin's own load focus (its 4-week load per band against its target range) as a second opinion |
| Coach | Ask the coach anything in your own words (what am I doing wrong?) - a short card, the biggest lever first. One-tap analyses by Claude as short cards that remember the previous card of their kind, accept your 👍/👎 and can be deleted. A card is a conversation: ask on under it, and every answer is |
| written with the whole thread; it may offer a next step (Plan my week) as a button that starts with | |
| that conversation; and what you say about yourself there is noted for the coach, each fact checked against your own words. Two start here (Why is VO2max moving? · Review my week); the other two start where their subject is — Should I train today? on the Today tab, Analyze this run on a run | |
| You | Your week, the foundation the planner goes by: runs per week, your days, long run, days you can't run, another sport - read from your history and kept up to date, and yours to change: what you set wins until you hand it back. For your coach: a note in your own words ("gym Mon, Wed, Fri", "less time until December") the coach reads before every answer. And what the coach has learned about you, each with its evidence: how consistent you are, your intensity pattern, the VO2max trend, Garmin's load focus, resting-HR baseline and zones - and since when, where something changed. Every card and the MCP tool get_athlete_profile read all three |
How it works
flowchart TD
G[Garmin Connect] -- "token resume, read" --> S[sync.py]
S --> DB[(SQLite<br/>~/.runspector)]
DB --> L[logic.py<br/>readiness · decision<br/>intervals · bands]
L --> SNAP[snapshot.py]
SNAP --> WEB[web app<br/>127.0.0.1:8765]
L --> MCP[MCP server<br/>18 tools<br/>14 read-only · sync · check-in · apply · undo]
WEB -- "spawn job" --> A["claude --print<br/>(your Claude sign-in)"]
A -- "only mcp__runspector__*" --> MCP
A -- "JSON card" --> WEB
MCP --- CC[Claude Code / Desktop]
Runspector MCP questions
How do I add Runspector MCP to Claude Code?
Run claude mcp add runspector -- uvx runspector mcp in your terminal. Add --scope user to make it available in every project.
How do I add Runspector MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Runspector MCP provide?
It exposes 18 tools, including get_athlete_profile, get_coaching_reference, get_training_readiness, get_recovery_summary, get_daily_metrics.
Does Runspector require an API key?
No, it does not require an API key. Your own Claude Code sign-in is sufficient for the coaching features.
Can I use the free Claude plan with the coach cards?
No, the coach cards require a paid Claude subscription (Pro, Max, Team, or Enterprise) or an Anthropic Console account.