TUTORIAL · 5 MINUTES

Connect your AI assistant to your Garmin watch

Running Workout exposes an MCP server: a standard bridge that lets an AI assistant read your training and write workouts to your Garmin. This guide shows you how to plug it in, whichever assistant you use.

What is an MCP server?

MCP (Model Context Protocol) is an open standard that lets an AI assistant connect to an outside service. Once the connector is added, your assistant gains tools: it can read your activities and create workouts on your Garmin account. You install nothing on your computer — we host the server.

Before you start

One step shared by all three assistants, and an address to keep handy.

Create your account and connect Garmin

On runningworkout.fr, click “Connect Garmin”. You authorise Running Workout from Garmin Connect: your password is never sent to us, and you can revoke access at any time. At the end of sign-up, the “AI assistant” step offers the “Add to Claude” and “Add to ChatGPT” buttons.

Keep the server address handy

With Claude and ChatGPT, one button is enough: nothing to copy. The address is for Gemini, Claude Code or a custom connector. It is the same for everyone and holds no secret: you sign in afterwards, in your browser.

MCP server address

https://www.runningworkout.fr/mcp

Choose your assistant

Connecting with Claude

Running Workout is in Claude’s connector directory, open on every plan, the free one included: the button below is all you need. Once added on claude.ai or in the desktop app, it also works on mobile and in Cowork.

Add to Claude

Opens the official Running Workout listing in Claude: click “Connect”, then authorise your account. The steps below walk through it, along with the fallback, which also works for any other MCP client.

1

Open the Running Workout listing

Click “Add to Claude” above: the official listing opens in Claude’s connector directory. Or, in Claude: “Customize” > “Connectors”, the “+” button, then search for Running Workout.
2

Connect

Click “Connect” (sign in to Claude first if the listing asks you to). Claude sends you to runningworkout.fr: sign in, then approve the authorisation screen listing what the assistant will be able to do.
3

Ask for your first workout

Open a new conversation and ask: Claude can bring in Running Workout on its own. If it answers without your data, open the “+” menu, hover over “Connectors” and switch on Running Workout for this conversation.
4

Fallback: custom connector

If the listing is not offered to you: “Customize” > “Connectors”, the “+” button, then add a custom connector (“Custom”, then “Web”, in the latest version). Paste the server address, click “Continue” until you reach “Add”, then approve the authorisation. Claude’s free plan allows only one.

In the terminal, with Claude Code

One command is enough, then start authentication with the /mcp command.

claude mcp add --transport http running-workout \
  https://www.runningworkout.fr/mcp

Team and Enterprise accounts

The organisation owner first adds Running Workout from “Organization settings” > “Connectors” (“Browse connectors”, then “Add to your team”). Each member then clicks “Connect” from “Customize” > “Connectors”, with their own Garmin account.

Connecting with ChatGPT

Running Workout is a public plugin in ChatGPT’s directory. According to OpenAI, the directory is open on every plan; installation can depend on your plan, country and workspace.

Add to ChatGPT

Opens the official Running Workout page in ChatGPT: click “Install plugin”, then authorize your account.

1

Open the Running Workout page

In ChatGPT, open Plugins in the sidebar (web, desktop or mobile) and search for Running Workout. Quicker: the “Add to ChatGPT” button, at the end of sign-up or in your Running Workout Settings, opens the page.
2

Install the plugin

Click “Install plugin”. If it does not appear, installation is not open to your plan, country or workspace: see the manual setup below, or use Claude.
3

Authorise access

If ChatGPT asks, click “Connect”: you are redirected to runningworkout.fr to approve. Nothing else to fill in.
4

Ask for your first workout

ChatGPT uses installed plugins on its own when your request calls for them. To point it there, type @ and pick Running Workout.

Manual setup: Business, Enterprise and Edu

On the web, Plugins → the “+” button → “Add custom MCP server”: paste the server address under Connection, choose OAuth, tick “I understand and want to continue”, then “Create as a plugin”, and install it. Developer mode is no longer needed. On Business, only admins and owners can do this; on Enterprise and Edu, so can members an admin has authorised. On ChatGPT Pro, a server added this way stays read-only.

Connecting with Gemini

In the US and in English, the Gemini app accepts the server address (gemini.google.com, Settings, Connected Apps, Custom apps). In the terminal, Gemini CLI now needs a paid Gemini API key or an enterprise licence; with a free Google account, Google points you to Antigravity CLI. Our team has not yet tried the Gemini app or Antigravity CLI with Running Workout. The steps below are for Gemini CLI.

1

Add the server

In your terminal, with Gemini CLI set up on your API key, run the command below. It registers the server under the name running-workout.
2

Or edit the configuration by hand

In ~/.gemini/settings.json, add this entry under mcpServers. Enabling oauth is enough: Gemini discovers the rest on its own. With Antigravity CLI, the entry goes in ~/.gemini/config/mcp_config.json, with serverUrl instead of httpUrl and no oauth line.
3

Authenticate

Type /mcp auth running-workout in Gemini CLI. Authorisation opens in your browser, you approve, and you are done. In Antigravity CLI, /mcp opens the server manager, which shows whether running-workout is connected.

gemini mcp add --transport http running-workout \
  https://www.runningworkout.fr/mcp

{
  "mcpServers": {
    "running-workout": {
      "httpUrl": "https://www.runningworkout.fr/mcp",
      "oauth": { "enabled": true }
    }
  }
}

What your assistant can send to your watch

Running, cycling or pool swimming: here are the targets you can ask for, sport by sport, and how to phrase them in plain language. Some have just been opened up to new sports; others remain specific to one.

infoGood to know

Your assistant writes directly to your Garmin Connect account. It never guesses: it uses the values from your profile (HR max, VMA, FTP, CSS) to turn a percentage into a real value. If one of these values is missing, it tells you and sends nothing to your watch rather than inventing a target — see Your athlete data.

What you can ask for	Swimming	How to say it
No target (free pace)		"20 min easy, no target"
Pace		"3 km at 4:30/km"
Percentage of VMA		"6 × 800 m at 95% VMA"
Percentage of HR max	to confirm	"45 min between 70 and 75% of HR max"
Heart rate in bpm	to confirm	"40 min between 140 and 150 bpm"
Heart rate zone	to confirm	"1 h in zone 2"
Power in watts		"3 × 10 min at 220-230 W"
Power zone		"20 min in power zone 4"
Cadence	to confirm	"holding 90 rpm" · "at 180 steps/min"
Swim pace (/100 m)		"8 × 100 m at 1:45/100 m"
Offset from your CSS		"6 × 200 m at CSS + 3 s"
Swim effort instruction (1-10)		"4 × 50 m descending"
Two targets at once Cycling only. Garmin rejects it for running (cadence can go in the step description). Not possible for swimming, for a format reason: the watch only reserves two target slots per step, and the second is already used by the length's primary target (pace, CSS or instruction).		"3 × 8 min at 250 W while holding 90 rpm"

Structure of a workout

Five possible intensities for a step: warm-up, active, recovery, rest, cool-down.
Repeat blocks, nested up to 5 levels deep — for example "3 × (5 × 200 m + 200 m recovery) with 3 min between blocks".
A step's duration can be given in time, in distance, or left open (the watch's "lap" button).
A workout can be placed directly on a date in your Garmin calendar.

What your assistant can read

The mirror of writing, and often overlooked:

the list of your completed activities, with duration, distance, average and max heart rate, pace, cadence, lengths, elevation gain, calories;
the detail of a completed workout: full summary, normalized power, effective cadence (zeros excluded), moving time, laps (up to 50), and for swimming the length-by-length detail (time, stroke, stroke count, SWOLF) when the file is available;
your athlete profile and its metrics, with the origin of each value;
your notes;
your calendar of planned workouts.

A useful asymmetry to know: activities and notes are read locally, with no Garmin call, so instantly. The calendar and writing workouts, on the other hand, go through Garmin.

Running

Every target in the table above is available. A percentage of VMA is translated into a real pace from YOUR VMA at the time it is sent; if you change it afterwards, workouts already sent do not move.

Cycling

Power is expressed in absolute watts, never as a percentage of FTP.

A step can carry two targets at once — power and cadence, for example.

.zwo export for Zwift

Your cycling workouts can be exported to .zwo format from the calendar, for Zwift and compatible apps. Worth knowing, because it can silently produce a wrong workout: .zwo does not accept watts, only a percentage of a reference FTP. Running Workout uses a fixed reference FTP of 160 W, written into the workout description. This value must match the setting in the app that reads the file, or every target ends up shifted by the same percentage, silently.

Pool swimming

Pool length is mandatory (25 m, 50 m, 25 yd…).

Steps are counted in distance, never in time — except rest steps, which are in seconds.

Stroke, drill and equipment can be specified for each step:

Freestyle · Backstroke · Breaststroke · Butterfly · Individual medley · Choice — Kick · Pull — Paddles · Pull buoy · Fins · Kickboard · Snorkel

A watch quirk worth knowing

When a repeat block ends with a rest step, the watch skips that last rest. If you want a pause before the next set, ask for an explicit rest step after the block.

Limits — stated clearly

Limit	Wording
Calendar	A calendar lookup covers at most 62 days.
Activities	At most 100 activities per request.
Readable workouts	Only workouts created through Running Workout can be read back in detail; ones built directly in Garmin Connect are invisible to your assistant.
Editing	A workout is never edited in place: it is deleted and re-created. There is no "edit" command — that is a deliberate choice, not a temporary limitation.
History	Activities from before you connected only exist if you have run an import.
Sports	Running, cycling and pool swimming. Not yet strength training, marked trail running, or a full triathlon.
Target resolution	A percentage (VMA, HR max) requires the matching value in your profile. If it is missing, the workout is not created, and your assistant explains what to do.

My assistant tells me it doesn't know my HR max.

That is the intended behaviour: without a declared HR max, no heart-rate-percentage target can be translated into a real value, and your assistant would rather tell you than send a wrong workout. Declare it by giving the number in conversation, or ask directly for a target in bpm, which does not depend on any profile data.

My assistant doesn't see my recent activities.

Activities arrive via Garmin notification, sometimes with a few minutes' delay. History from before you connected requires an explicit import from your dashboard.

The workout is on Garmin Connect but not on my watch.

That is the sync between Garmin Connect and your watch, independent of Running Workout — check that your watch has synced recently (Bluetooth or Wi-Fi).

My assistant can't find a workout I created in Garmin Connect.

Only workouts created through Running Workout can be read back in detail. A workout built by hand in Garmin Connect has no local copy to consult.

How do I remove a workout from my calendar without losing it?

Two different actions: unscheduling removes the date without touching the workout, which stays in your Garmin library; deleting removes the workout itself (and, with it, every scheduled date).

Your athlete data: where your numbers come from

VMA, FTP, CSS, HR max: where these numbers come from, who can change them, how to fix a wrong value, and how to read their history.

The origins of a value

Origin	What it means	Who writes it
historycomputed	Estimated automatically, every week, from your activities.	The system
verifiedtest	Value computed from an explicitly selected test	You, from the dashboard
auto_awesomeAI	Value declared via AI assistant	Your assistant, with your agreement
watchGarmin	Value inherited from your Garmin watch	Your watch, automatically

Priority rule

In this order: a value verified by test always wins; failing that, a value you declared to your assistant; failing that, an automatically computed value; only failing all of those, the value inherited from your watch or entered in Settings. One consequence worth knowing: a value declared to your assistant one day keeps outranking a more recent Garmin import, until you correct it yourself.

Weight, height and a few other fields can also be typed directly into Settings → My profile: they then carry the same "declared" badge as when your assistant records them for you, just through a different door.

Why this mechanism exists

An automatic calculation used to scan every workout without knowing which one was a test. It once produced an FTP of 167 W on a ramp test, where the correct formula gave 194 W: the 20-minute average smoothed out the easy first minutes of the ramp. Since then, VMA, FTP and CSS are no longer estimated in the background: you designate the test workout yourself, and the system applies the correct protocol's formula.

Declaring a test — the three protocols

VMA (running)

Protocol	When to use it	Formula
Continuous effort	A half-Cooper or VAMEVAL-style test, on a workout at a steady, sustained effort.	Best rolling average speed over 6 minutes.
Progressive test	A step test with increasing stages, to exhaustion.	Best 60-second average, last minute excluded.

Safety bounds: 8 to 25 km/h. Outside these bounds, the calculation is refused and nothing is recorded.

Prerequisite: the activity must have its detailed data ("GPS available" in the list).

FTP (cycling)

Protocol	When to use it	Formula
Steady effort	A classic 20-minute test at constant intensity.	Best average power over 20 minutes × 95%.
Ramp	A ramp test (+20 W/min until failure).	Best average over 60 seconds × 75%.

Bounds: 50 to 600 W.

Prerequisite: a power meter. The system spots ramp tests from the staircase shape of the power curve and pre-selects the right protocol — you confirm it.

CSS (swimming)

Critical swim speed is derived from two efforts at different distances.

Protocol	What you need
Two distances in the same workout (preferred)	A pool workout containing two efforts (for example 200 m then 400 m). The system suggests the laps; you tick exactly two.
Two separate workouts (fallback)	Two complete workouts at different distances.

Formula: CSS = (distance₂ − distance₁) ÷ (duration₂ − duration₁), converted to seconds/100 m. Constraints: distances between 150 and 800 m, a gap of at least 100 m, the longer effort must take more time. Result bounds: 50 to 180 s/100 m.

Consistency between lengths × pool length is also checked, with a 15% tolerance.

From the dashboard

Click the "test tube" icon on a tile, choose the test activity, run the calculation. This is the recommended path: the result is deterministic and traceable back to the source activity.

By talking to your assistant

"I did an FTP test yesterday, 210 W." It records it with the note "test result reported by you".

By correcting a sensor

"My watch counted 1,100 m but I swam 1,000." Recorded with the note "sensor correction confirmed by you".

What your assistant is not allowed to do

Your assistant can never record a value it simply inferred from your profile. It must rely on one of these real events: you reported a test result to it, it spotted a sensor inconsistency you confirmed, or it proposed an update and you said yes. Every recorded value carries which of these three reasons applies, and you can read it back.

HR max, resting HR and VO2max follow a different path: your watch sends them automatically (when it measures them), with nothing for you to ask. You can also type them yourself in Settings if your watch does not report them.

Reading and cleaning your history

Clicking a tile opens the full history of the statistic: every value, its date, its gap from the previous one, its origin, its method and any note.

Declared and test-derived values can be deleted. Computed values cannot: they regenerate at the next recalculation.

Recalculate

Updates the computed values from your current activities.

Recalculate the whole history

Rebuilds every computed value, week by week, up to 2 years back. Use it after a large import or a formula fix. Your tests and declarations are never touched.

The other data

Field	Where to set it	What it is used for
First name	Settings → My profile	Personalization
Email (optional)	Settings → My profile	Only used to reach you if needed (for example, an incident on your account); never shared with a third party or used for marketing.
Sex, age	Settings → My profile	Physiological estimates
Weight	Settings → My profile	Required to compute watts/kg
Followed sports	Settings → My sports	Filters what the dashboard shows. Data for unchecked sports keeps being computed, it is only hidden.
HR max, resting HR, VO2max	Inherited automatically from your Garmin watch (if it measures them), or declared in Settings otherwise	Translate HR percentages into bpm and refine the load calculation. Honest limit worth knowing: VO2max has no recoverable history — only values measured after you connected ever appear, never earlier ones.
Language	Header selector	Your assistant writes the name and description of your workouts in this language

Volume, load and ACWR

Volume: total training duration over 30 days, all sports combined.
Load (TRIMP): duration weighted by heart-rate intensity.
ACWR: ratio between your load over the last 7 days and your average load over the last 42.

Value	Colour	Reading
< 0.8		Load trending down — tapering, or a break
0.8 – 1.3		Progression zone
1.3 – 1.5		Rising fast, be careful
> 1.5		Rising too fast, higher injury risk

⚠ These are training indicators, not medical advice.

Why doesn't the automatic calculation recompute my VMA, FTP or CSS anymore?

Because an automatic scan once got it wrong (see "Why this mechanism exists" above). These three values are now only computed on an activity you designate yourself as a test, with the correct protocol's formula — never in the background.

Check that it works

Ask your assistant these two questions. The first reads your data, the second writes to your watch.

« List my last 3 activities »

You should see your real sessions, with duration, distance and heart rate.

« Create 8x400 m at 95% vVO2max for Thursday »

The workout appears in Garmin Connect and on your watch, scheduled on the right day.

check_circle If both requests work, everything is in place.

If it does not work

My assistant sees no tools, what should I do?

The connector or plugin may be switched off in the current conversation. In Claude, open the “+” menu, hover over “Connectors” and switch on Running Workout; in ChatGPT, type @ and pick Running Workout. Also start a new conversation after adding it.

The “Install plugin” button does not appear in ChatGPT

According to OpenAI, installing a plugin depends on your plan, country and workspace. In a workspace, ask an admin to check that the plugin is allowed. On Business, Enterprise or Edu, adding the server by hand is still possible (see above); otherwise, Claude accepts Running Workout on every plan.

Authorisation fails or loops

Sign in on runningworkout.fr first and check your Garmin account is linked. The authorisation screen needs an active session to know which athlete to attach the assistant to.

How do I remove an assistant’s access?

In your Running Workout Settings, “Connected assistants” section: each authorisation can be revoked separately with “Revoke”, and access is cut immediately.

Ready to try?

Connect your watch, plug in your assistant, and ask for your first workout.

watch Connect Garmin — free to start

Resources

What you need to know to have an AI write your sessions: what the Garmin API allows, what existing MCP servers are worth, and the targets specific to each sport.

Connect your AI assistant to your Garmin watch

What is an MCP server?

Before you start

Create your account and connect Garmin

Keep the server address handy

Choose your assistant

Connecting with Claude

Open the Running Workout listing

Connect

Ask for your first workout

Fallback: custom connector

In the terminal, with Claude Code

Connecting with ChatGPT

Open the Running Workout page

Install the plugin

Authorise access