MCP · Running · COROS Training Hub

Running‑first
MCP server
for COROS.

Author, edit, and schedule running workouts from Claude Code, Claude Desktop, Codex, or Cursor. Pace‑based intervals, repeat groups, plan‑embedded edits — plus sleep, HRV, training load, and activity exports.

$ uv tool install coros-training-mcp
$ coros-mcp setup

Get started View on GitHub ↗

What it does

Running workout authoring

Pace‑based reps (4:05‑4:15/km), distance or time targets, repeat groups, HR zones. One shared schema across create and update.

Edit scheduled runs

Clone‑and‑swap edits — change rep count, pace, or recovery without losing the calendar entry. Works for library workouts and plan‑embedded programs inside subscribed training plans.

Strength circuits

Create from the COROS exercise catalog. Edit reps, duration, rest, or swap exercises without recreating the workout.

Training data

Sleep stages, HRV, resting HR, training load, VO₂max, stamina, and activity exports (GPX, FIT, TCX, KML, CSV).

See it in action

A real interaction with Claude. The human prompt maps to a single MCP tool call using the shared run‑step schema — pace parsing, repeat groups, and sensible defaults all flow from one compact JSON body.

You

Build me a 5×1km threshold session at 4:05–4:15/km with 2‑minute jog recoveries. 2 km warm‑up, 1.5 km cool‑down.

Claude

Creating the workout now.

→ coros · create_run_workout

{
  "name": "Threshold 5×1km",
  "steps": [
    { "kind": "warmup",   "target_type": "distance", "target_distance_meters": 2000 },
    { "repeat": 5, "name": "Main Set", "steps": [
        { "kind": "training", "target_distance_meters": 1000, "pace": "4:05-4:15/km" },
        { "kind": "rest",     "target_type": "time", "target_duration_seconds": 120 }
      ] },
    { "kind": "cooldown", "target_type": "distance", "target_distance_meters": 1500 }
  ]
}

✓ workout_id "476942477474054144" · 8.5 km · ~42 min

Done — Threshold 5×1km is in your COROS library. 8.5 km total. Want me to schedule it for a specific day?

You

Actually make it 6 reps, and put it on Tuesday.

Claude

→ coros · update_run_workout

{ "workout_id": "476942…", "step_updates": [{ "step_name": "Main Set", "repeat": 6 }] }

→ coros · schedule_workout

{ "workout_id": "476943…", "happen_day": "20260428" }

Updated to 6 reps (9.5 km total) and scheduled for Tue Apr 28. Watch will pick it up on next sync.

Local & private

This is a local MCP. It runs on your machine as a subprocess of your AI assistant — nothing is hosted, nothing is proxied, no third-party server sees your requests or your data.

Credentials stay on your machine

Your COROS email and password are stored in your OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service), or an AES‑encrypted file fallback. They are only ever sent over TLS directly to teamapi.coros.com.

No public internet exposure

The MCP speaks stdio to your local assistant. There is no network listener, no inbound port, no tunnel. Traffic is outbound only, to COROS.

No analytics, no telemetry

Zero pings home. Zero third‑party services. The repository is open source under the MIT license — every request the MCP can make is auditable in under an hour of reading.

Revoke in seconds

coros-mcp uninstall removes the MCP entry from your assistants and clears your stored credentials. Or delete the keyring entry directly — no remote state to clean up.

Install

$ uv tool install coros-training-mcp
$ coros-mcp setup

No API key needed. The wizard asks for your COROS email, password, and region, verifies them against the COROS API, stores the token in your OS keyring, and registers the MCP with your detected AI assistants. Pre‑existing MCP entries are preserved byte‑for‑byte.

Using pipx instead

$ pipx install coros-training-mcp
$ coros-mcp setup

Requirements

Python ≥ 3.11 (fetched automatically by uv tool install)
A COROS Training Hub account
macOS, Linux, or Windows

Upgrading & uninstalling

$ uv tool upgrade coros-training-mcp
$ coros-mcp setup --reconfigure   # change creds or add assistants
$ coros-mcp uninstall              # remove from assistants

What setup looks like

coros-mcp setup is a single linear wizard. Here's a real run on a machine with Claude Code and Claude Desktop installed — you answer four prompts, everything else is automatic.

~ / coros‑mcp setup

$ coros-mcp setup

Coros MCP — setup

Credentials will be stored in your system keyring.

? Coros email:    you@example.com
? Coros password: ●●●●●●●●●●●●
? Region:         EU  (teameuapi.coros.com)

Verifying credentials against the EU API…
✓ Authenticated as user 458991455476662278.
  Mobile token was skipped and will be fetched lazily on the first sleep query.

Detected 2 assistants on this machine.

? Install Coros MCP into which assistants?
  ◉ Claude Code (CLI)
  ◉ Claude Desktop

Installing with command: /Users/you/.local/bin/coros-mcp serve

  ✓ Claude Code:    installed — registered via `claude mcp add`
  ✓ Claude Desktop: installed — wrote ~/Library/Application Support/Claude/claude_desktop_config.json

Running post-install smoke test (booting server over stdio)…
✓ Smoke test passed — coros-mcp responded to initialize OK

Next steps:
  • Claude Desktop: restart the app so it picks up the new MCP entry.
  • Claude Code: ready to go — no restart needed.

Try it:
  "What workouts do I have scheduled this week?"
  "What was my HRV trend over the past month?"

Total time: under a minute. Rerun with --reconfigure to add another assistant later. The wizard never writes plaintext credentials to disk and refuses to overwrite unparseable config files.

Try it

More prompts to throw at your assistant once installed:

Create a 5×1km threshold workout at 4:05‑4:15/km with 2‑minute jog recovery.
Change my Tuesday VO₂ workout to 6 reps instead of 5.
Move Thursday's tempo run to Friday.
What was my HRV trend over the past month?
How much deep sleep and REM did I get last week?
Export my Saturday long run to GPX.

Tools exposed

list_workouts · get_workout · create_run_workout · update_run_workout · get_run_workout_schema

create_strength_workout · update_workout · get_strength_workout_schema · list_exercises · delete_workout

list_scheduled_workouts · schedule_workout · move_scheduled_workout · replace_scheduled_workout · remove_scheduled_workout

get_daily_metrics · get_sleep_data · list_activities · get_activity_detail · export_activity_file

Running‑first MCP server for COROS.