coros-mcp

[!IMPORTANT]

This is an unofficial, community-built project and is not affiliated with or endorsed by COROS.

COROS has since launched their official MCP server: coroslab/COROS-MCP.

If you are looking for an officially supported integration, please use that instead.

This project continues to exist as a community alternative and may offer different or complementary features.

A Model Context Protocol (MCP) server that fetches sleep, HRV, and training data from the unofficial Coros API and exposes them to AI assistants like Claude.

No API key required. This server authenticates directly with your Coros Training Hub credentials. Your token is stored securely in your system keyring (or an encrypted local file as fallback), never transmitted anywhere except to Coros.

What You Can Do

Ask your AI assistant questions like:

• "How much deep sleep and REM did I get last week?"
• "What was my HRV trend over the last 4 weeks?"
• "Show me my resting heart rate and training load for last week"
• "How many steps did I average per day this month?"
• "List my rides from last month"
• "Show me the details of my last long ride"
• "Create a 90-minute sweet spot workout for me"
• "What's on my training calendar next week?"
• "Schedule my VO2 workout for Thursday"
• "Create a 20-minute strength circuit with squats, lunges, and planks"

Features

| Tool | Description | |------|-------------| | authenticate_coros | Log in with email and password — token stored securely in keyring | | authenticatecorosmobile | Log in to the mobile API only (useful for sleep data troubleshooting) | | checkcorosauth | Check whether a valid auth token is present | | getdailymetrics | Fetch daily metrics (HRV, resting HR, training load, VO2max, stamina, and more) for n weeks (default: 4) | | getsleepdata | Fetch nightly sleep stages (deep, light, REM, awake) and sleep HR for n weeks (default: 4) | | list_activities | List activities for a date range with summary metrics | | getactivitydetail | Fetch full detail for a single activity (laps, HR zones, power zones) | | listworkouttemplates | List reusable workout templates saved in the library | | saveworkouttemplate | Save a reusable cycling/intervals workout template (named steps, power targets) | | savestrengthworkout_template | Save a reusable strength workout template (sets, reps, or timed exercises) | | deleteworkouttemplate | Delete a saved workout template from the library | | listplannedactivities | List planned workouts from the Coros training calendar | | schedule_workout | Schedule a one-off cycling/intervals workout for a date (no library entry) | | schedulestrengthworkout | Schedule a one-off strength workout for a date (no library entry) | | scheduleworkouttemplate | Schedule an existing library template on a calendar day | | removescheduledworkout | Remove a scheduled workout from the calendar | | list_exercises | Browse the Coros exercise catalogue, especially for strength workouts | | synccorosdata | Backfill all data into the local SQLite cache for a date range | | getcachestatus | Show coverage (record counts and date ranges) of the local cache |

Setup

Option A: Auto-Setup with Claude Code

If you have Claude Code, paste this prompt:

Set up the Coros MCP server from https://github.com/cygnusb/coros-mcp — clone it, create a venv, install it with pip install -e ., add it to my MCP config, then tell me to run 'coros-mcp auth' in my terminal to authenticate.

Claude will handle the installation and guide you through configuration.

Option B: Manual Setup

Step 1: Install

git clone https://github.com/cygnusb/coros-mcp.git
cd coros-mcp
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

Or with uv:

uv pip install -e .

Step 2: Add to Claude Code

claude mcp add coros -- /path/to/coros-mcp/.venv/bin/coros-mcp serve

To limit the MCP to a specific project only (recommended):

cd /path/to/your/project
claude mcp add --scope project coros -- /path/to/coros-mcp/.venv/bin/coros-mcp serve

Or add to Claude Desktop (~/Library/Application Support/Claude/claudedesktopconfig.json):

{
  "mcpServers": {
    "coros": {
      "command": "/path/to/coros-mcp/.venv/bin/coros-mcp",
      "args": ["serve"]
    }
  }
}

Step 3: Authenticate

Option A — .env file (recommended for project-scoped setups):

Create a .env file in your project directory:

COROS_EMAIL=you@example.com
COROS_PASSWORD=yourpassword
COROS_REGION=eu

The server authenticates automatically on the first request and re-authenticates transparently whenever the token expires. No manual auth step needed.

Option B — Manual authentication:

Run the following command in your terminal — outside of any Claude session:

coros-mcp auth

You will be prompted for your email, password, and region (eu, us, or asia). This stores both the Training Hub web token and the mobile API token (used for sleep data). Your credentials are sent directly to Coros and the tokens are stored securely in your system keyring (or an encrypted local file as fallback). You only need to do this once — the tokens persist across restarts.

Note: The mobile login (apieu.coros.com) will log you out of the Coros mobile app on your phone. If you want to avoid this, use coros-mcp auth-web instead — it stores only the web token, and the mobile token will be obtained automatically when you first request sleep data.

Other auth commands:

coros-mcp serve         # Start the MCP server (used by Claude Code / Claude Desktop)
coros-mcp auth-web      # Web API only — skips mobile login (sleep data obtained lazily)
coros-mcp auth-mobile   # Mobile API only (sleep data)
coros-mcp auth-status   # Check if authenticated
coros-mcp auth-clear    # Remove stored tokens

Tool Reference

authenticate_coros

Log in with your Coros credentials. The auth token is stored securely in your system keyring (or an encrypted file as fallback).

{ "email": "you@example.com", "password": "yourpassword", "region": "eu" }

Returns: authenticated, user_id, region, message

authenticatecorosmobile

Authenticate with the Coros mobile API only. This is mainly useful if you need to restore sleep-data access without redoing full web authentication.

{ "email": "you@example.com", "password": "yourpassword", "region": "eu" }

Returns: authenticated, user_id, region, message

checkcorosauth

Check whether valid web and mobile tokens are stored and how long the web token remains valid.

{}

Returns: authenticated, userid, region, expiresinhours, mobileauthenticated, mobiletokenstatus

getdailymetrics

Fetch daily metrics for a configurable number of weeks (default: 4).

{ "weeks": 4 }

Returns: records (list), count, date_range

Each record includes:

| Field | Source | Description | |-------|--------|-------------| | date | — | Date (YYYYMMDD) | | avgsleephrv | dayDetail | Nightly HRV (RMSSD ms) | | baseline | dayDetail | HRV rolling baseline | | rhr | dayDetail | Resting heart rate (bpm) | | training_load | dayDetail | Daily training load | | trainingloadratio | dayDetail | Acute/chronic training load ratio | | tired_rate | dayDetail | Fatigue rate | | ati / cti | dayDetail | Acute / chronic training index | | distance / duration | dayDetail | Distance (m) / duration (s) | | vo2max | analyse (merge) | VO2 Max (last ~28 days) | | lthr | analyse (merge) | Lactate threshold heart rate (bpm) | | ltsp | analyse (merge) | Lactate threshold pace (s/km) | | stamina_level | analyse (merge) | Base fitness level | | staminalevel7d | analyse (merge) | 7-day fitness trend |

getsleepdata

Fetch nightly sleep stage data for a configurable number of weeks (default: 4).

{ "weeks": 4 }

Returns: records (list), count, date_range

Each record includes:

| Field | Description | |-------|-------------| | date | Date (YYYYMMDD) — the morning after the sleep | | totaldurationminutes | Total sleep in minutes | | phases.deep_minutes | Deep sleep | | phases.light_minutes | Light sleep | | phases.rem_minutes | REM sleep | | phases.awake_minutes | Time awake during the night | | phases.nap_minutes | Daytime nap time (null if none) | | avg_hr | Average heart rate during sleep | | min_hr | Minimum heart rate during sleep | | max_hr | Maximum heart rate during sleep | | quality_score | Sleep quality score (null if not computed) |

Note: Sleep data is fetched from the Coros mobile API (apieu.coros.com), which uses a separate token from the Training Hub web API. coros-mcp auth obtains both tokens, but doing so logs you out of the Coros mobile app. Use coros-mcp auth-web to skip mobile login — the mobile token is then obtained automatically on the first sleep data request. The token expires after ~1 hour but refreshes automatically on subsequent requests.

list_activities

List activities for a date range.

{ "startday": "20260101", "endday": "20260305", "page": 1, "size": 30 }

Returns: activities (list), total_count, page

Each activity includes: activityid, name, sporttype, sportname, starttime, endtime, durationseconds, distancemeters, avghr, maxhr, calories (in cal — divide by 1000 for kcal), trainingload, avgpower, normalizedpower, elevation_gain

getactivitydetail

Fetch full detail for a single activity. Requires the sporttype from listactivities.

{ "activityid": "469901014965714948", "sporttype": 200 }

Returns full activity data including laps, HR zones, power zones, and all sport-specific metrics.

Note: Large time-series arrays (graphList, frequencyList, gpsLightDuration) are stripped from the response to keep it manageable.

listworkouttemplates

List reusable workout templates saved in the Coros library.

{}

Returns: workouts (list), count

Each entry includes: id, name, sporttype, sportname, estimatedtimeseconds, exercisecount, exercises (list of steps with name, durationseconds, intensitylow, intensityhigh, sets)

saveworkouttemplate

Save a reusable cycling/intervals workout template to the Coros library. The template appears in the Coros app and can be synced to the watch. Steps can be plain steps or repeat groups for intervals.

⚠️ This persists to the library indefinitely. For a one-off workout for a specific date, use scheduleworkout instead — it builds the workout inline and leaves no library entry.

Plain steps:

{
  "name": "Sweet Spot 90min",
  "sport_type": 2,
  "steps": [
    {"name": "15:00 Warmup",     "durationminutes": 15, "intensitylow": 148, "intensity_high": 192},
    {"name": "20:00 Sweet Spot", "durationminutes": 20, "intensitylow": 260, "intensity_high": 275},
    {"name": "5:00 Rest",        "durationminutes":  5, "intensitylow": 100, "intensity_high": 150},
    {"name": "20:00 Sweet Spot", "durationminutes": 20, "intensitylow": 260, "intensity_high": 275},
    {"name": "30:00 Cooldown",   "durationminutes": 30, "intensitylow": 100, "intensity_high": 192}
  ]
}

With repeat groups (intervals):

{
  "name": "3×10min Sweet Spot",
  "sport_type": 2,
  "steps": [
    {"name": "Warmup",    "durationminutes": 10, "intensitylow": 150, "intensity_high": 200},
    {"repeat": 3, "steps": [
      {"name": "Sweet Spot", "durationminutes": 10, "intensitylow": 265, "intensity_high": 285},
      {"name": "Recovery",   "durationminutes":  3, "intensitylow": 150, "intensity_high": 175}
    ]},
    {"name": "Cooldown",  "durationminutes": 11, "intensitylow": 150, "intensity_high": 200}
  ]
}

sport_type: 2 = Indoor Cycling (default), 200 = Road Bike

Returns: workoutid, name, totalminutes, steps_count, message

savestrengthworkout_template

Save a reusable strength workout template to the Coros library. Exercises must come from the Coros exercise catalogue.

⚠️ This persists to the library indefinitely. For a one-off workout for a specific date, use schedulestrengthworkout instead — it builds the workout inline and leaves no library entry.

{
  "name": "Leg Circuit",
  "sets": 3,
  "exercises": [
    {
      "origin_id": "54",
      "name": "T1061",
      "overview": "sidstrengthsquats",
      "target_type": 3,
      "target_value": 12,
      "rest_seconds": 45,
      "sets": 3,
      "weight_kg": 80
    },
    {
      "origin_id": "130",
      "name": "T1176",
      "overview": "sidstrengthplank",
      "target_type": 2,
      "target_value": 60,
      "rest_seconds": 30
    }
  ]
}

target_type: 2 = time in seconds, 3 = reps

sets (per exercise, optional): consecutive sets of that exercise before moving on. Use this instead of duplicating the exercise entry. Defaults to 1.

sets (top-level): full-circuit repetitions — repeats the entire exercise list. Defaults to 1.

Weight fields (per exercise, optional):

| Field | Description | |-------|-------------| | weight_kg | Prescribed weight in kg (e.g. 80) | | weightlbs | Prescribed weight in pounds (e.g. 176.4) — mutually exclusive with weightkg |

• Omitting both fields renders the exercise as Bodyweight in the Coros app.
• Setting weight_kg: 0 renders as "0.00 kg" — distinct from Bodyweight.
• For dumbbell exercises, the weight is per hand by convention (the app shows a single value).
• kg and lbs can be mixed across exercises within the same workout.

deleteworkouttemplate

Delete a saved workout template from the Coros library.

{ "workout_id": "476023839273435149" }

The workoutid comes from listworkout_templates.

Returns: deleted, workout_id, message

listplannedactivities

List planned activities from the Coros training calendar.

{ "startday": "20260309", "endday": "20260316" }

Returns: schedule (dict with entities and programs sub-lists), count (number of scheduled entities), date_range

schedule_workout

Schedule a one-off cycling/intervals workout for a specific date. Builds the workout inline and posts straight to the calendar — does not create a library entry. This is the common case.

Same parameters as saveworkouttemplate, plus happenday (YYYYMMDD) and an optional sortno (order within the day).

{
  "name": "Z2 Recovery",
  "happen_day": "20260312",
  "sport_type": 2,
  "steps": [
    {"name": "Easy spin", "durationminutes": 60, "intensitylow": 150, "intensity_high": 200}
  ]
}

Returns: scheduled, name, happenday, totalminutes, steps_count, response

schedulestrengthworkout

Schedule a one-off strength workout for a specific date. Builds the workout inline and posts straight to the calendar — does not create a library entry.

Same parameters as savestrengthworkouttemplate, plus happen_day.

{
  "name": "Push Day",
  "happen_day": "20260312",
  "sets": 1,
  "exercises": [ ... ]
}

Returns: scheduled, name, happenday, sets, exercisecount, response

scheduleworkouttemplate

Schedule an existing library template on a calendar day.

{ "workoutid": "1234567890", "happenday": "20260312", "sort_no": 1 }

The workoutid comes from listworkouttemplates. For one-off workouts that don't need a library entry, use scheduleworkout or schedulestrength_workout instead.

{
  "plan_id": "987654321",
  "idinplan": "1234567890",
  "planprogramid": "1234567890"
}

{ "sport_type": 4 }

{ "startday": "20230101", "endday": "20260514" }

coros-mcp sync --from 20230101

{}

coros-mcp/
├── coros_mcp/
│   ├── server.py      # MCP server with tool definitions
│   ├── coros_api.py   # Coros API client (auth, requests, parsers)
│   ├── models.py      # Pydantic data models
│   ├── cli.py         # CLI entry point (serve, auth, sync, cache-status, …)
│   ├── auth/          # Token storage (keyring + encrypted file fallback)
│   └── cache/         # SQLite cache layer (store, sync, utils)
├── tests/             # pytest test suite
├── pyproject.toml     # Project metadata & dependencies
└── docs/
    └── mobile-token.md  # Mobile API token background (legacy reference)