Skip to content
Back to search

coros-mcp

MCP server for AI assistants to read and manage Coros fitness data: sleep, HRV, daily metrics, activities, and structured workouts via the unofficial Coros API

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/cygnusb/coros-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/cygnusb/coros-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cygnusb--coros-mcp/badge.svg)](/listings/cygnusb--coros-mcp)

HTML

<a href="/listings/cygnusb--coros-mcp"><img src="/api/listings/cygnusb--coros-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option A: Auto-Setup with Claude Code

If you have [Claude Code](https://claude.ai/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/claude_desktop_config.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

Step 4 (optional): Restrict the toolset for autonomous agents

When the MCP client is an autonomous agent or a smaller open-weight model (e.g. [hermes-agent](https://github.com/NousResearch/hermes-agent) with a DeepSeek/Hermes model), two env vars harden the server:

COROS_MCP_TOOLSET=readonly       # expose only the 12 read tools
COROS_MCP_HIDE_AUTH_TOOLS=1      # hide authenticate_* (credentials never enter the model context)

- `COROS_MCP_TOOLSET=readonly` hides everything that writes to your Coros account (save/schedule/update/delete tools) plus the low-level raw escape hatches, leaving: `get_help`, `check_coros_auth`, `get_daily_metrics`, `get_sleep_data`, `list_activities`, `get_activity_detail`, `list_workout_templates`, `list_training_plans`, `list_planned_activities`, `list_exercises`, `sync_coros_data`, `get_cache_status`. A smaller tool list also improves tool-calling reliability of non-frontier models. Default: `full` (all 26 tools). - `COROS_MCP_HIDE_AUTH_TOOLS=1` removes the two `authenticate_*` tools so your password can never travel through the model context or agent logs.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 570 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # coros-mcp
  2. [![CI](https://github.com/cygnusb/coros-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/cygnusb/coros-mcp/actions/workflows/ci.yml)
  3. [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
  4. [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  5. [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
  6. > [!IMPORTANT]
  7. > **This is an unofficial, community-built project and is not affiliated with or endorsed by COROS.**
  8. >
  9. > COROS has since launched their **official MCP server**: [coroslab/COROS-MCP](https://github.com/coroslab/COROS-MCP).
  10. > If you are looking for an officially supported integration, please use that instead.
  11. >
  12. > This project continues to exist as a community alternative and may offer different or complementary features.
  13. A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that fetches sleep, HRV, and training data from the unofficial Coros API and exposes them to AI assistants like Claude.
  14. **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.
  15. ## What You Can Do
  16. Ask your AI assistant questions like:
  17. - "How much deep sleep and REM did I get last week?"
  18. - "What was my HRV trend over the last 4 weeks?"
  19. - "Show me my resting heart rate and training load for last week"
  20. - "How many steps did I average per day this month?"
  21. - "List my rides from last month"
  22. - "Show me the details of my last long ride"
  23. - "Create a 90-minute sweet spot workout for me"
  24. - "What's on my training calendar next week?"
  25. - "Schedule my VO2 workout for Thursday"
  26. - "Create a 20-minute strength circuit with squats, lunges, and planks"
  27. ## Features
  28. | Tool | Description |
  29. |------|-------------|
  30. | `authenticate_coros` | Log in with email and password — token stored securely in keyring |
  31. | `authenticate_coros_mobile` | Log in to the mobile API only (useful for sleep data troubleshooting) |
  32. | `check_coros_auth` | Check whether a valid auth token is present |
  33. | `get_daily_metrics` | Fetch daily metrics (HRV, resting HR, training load, VO2max, stamina, and more) for n weeks (default: 4) |
  34. | `get_sleep_data` | Fetch nightly sleep stages (deep, light, REM, awake) and sleep HR for n weeks (default: 4) |
  35. | `list_activities` | List activities for a date range with summary metrics |
  36. | `get_activity_detail` | Fetch full detail for a single activity (laps, HR zones, power zones) |
  37. | `list_workout_templates` | List reusable workout templates saved in the library |
  38. | `save_workout_template` | Save a reusable cycling/intervals workout template (named steps, power targets) |
  39. | `save_strength_workout_template` | Save a reusable strength workout template (sets, reps, or timed exercises) |
  40. | `delete_workout_template` | Delete a saved workout template from the library |
  41. | `list_planned_activities` | List planned workouts from the Coros training calendar |
  42. | `schedule_workout` | Schedule a one-off cycling/intervals workout for a date (no library entry) |
  43. | `schedule_strength_workout` | Schedule a one-off strength workout for a date (no library entry) |
  44. | `schedule_workout_template` | Schedule an existing library template on a calendar day |
  45. | `remove_scheduled_workout` | Remove a scheduled workout from the calendar |
  46. | `list_exercises` | Browse the Coros exercise catalogue, especially for strength workouts |
  47. | `sync_coros_data` | Backfill all data into the local SQLite cache for a date range |
  48. | `get_cache_status` | Show coverage (record counts and date ranges) of the local cache |
  49. ---
  50. ## Setup
  51. ### Option A: Auto-Setup with Claude Code
  52. If you have [Claude Code](https://claude.ai/code), paste this prompt:
  53. ```
  54. 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.
  55. ```
  56. Claude will handle the installation and guide you through configuration.
  57. ### Option B: Manual Setup
  58. #### Step 1: Install
  59. ```bash
  60. git clone https://github.com/cygnusb/coros-mcp.git
  61. cd coros-mcp
  62. python3 -m venv .venv
  63. source .venv/bin/activate # Windows: .venv\Scripts\activate
  64. pip install -e .
  65. ```
  66. Or with `uv`:
  67. ```bash
  68. uv pip install -e .
  69. ```
  70. #### Step 2: Add to Claude Code
  71. ```bash
  72. claude mcp add coros -- /path/to/coros-mcp/.venv/bin/coros-mcp serve
  73. ```
  74. To limit the MCP to a specific project only (recommended):
  75. ```bash
  76. cd /path/to/your/project
  77. claude mcp add --scope project coros -- /path/to/coros-mcp/.venv/bin/coros-mcp serve
  78. ```
  79. Or add to Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
  80. ```json
  81. {
  82. "mcpServers": {
  83. "coros": {
  84. "command": "/path/to/coros-mcp/.venv/bin/coros-mcp",
  85. "args": ["serve"]
  86. }
  87. }
  88. }
  89. ```
  90. #### Step 3: Authenticate
  91. **Option A — `.env` file (recommended for project-scoped setups):**
  92. Create a `.env` file in your project directory:
  93. ```
  94. COROS_EMAIL=you@example.com
  95. COROS_PASSWORD=yourpassword
  96. COROS_REGION=eu
  97. ```
  98. The server authenticates automatically on the first request and re-authenticates transparently whenever the token expires. No manual auth step needed.
  99. **Option B — Manual authentication:**
  100. Run the following command in your terminal — **outside** of any Claude session:
  101. ```bash
  102. coros-mcp auth
  103. ```
  104. 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.
  105. > **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.
  106. **Other auth commands:**
  107. ```bash
  108. coros-mcp serve # Start the MCP server (used by Claude Code / Claude Desktop)
  109. coros-mcp auth-web # Web API only — skips mobile login (sleep data obtained lazily)
  110. coros-mcp auth-mobile # Mobile API only (sleep data)
  111. coros-mcp auth-status # Check if authenticated
  112. coros-mcp auth-clear # Remove stored tokens
  113. ```
  114. #### Step 4 (optional): Restrict the toolset for autonomous agents
  115. When the MCP client is an autonomous agent or a smaller open-weight model
  116. (e.g. [hermes-agent](https://github.com/NousResearch/hermes-agent) with a
  117. DeepSeek/Hermes model), two env vars harden the server:
  118. ```
  119. COROS_MCP_TOOLSET=readonly # expose only the 12 read tools
  120. COROS_MCP_HIDE_AUTH_TOOLS=1 # hide authenticate_* (credentials never enter the model context)
  121. ```
  122. - `COROS_MCP_TOOLSET=readonly` hides everything that writes to your Coros
  123. account (save/schedule/update/delete tools) plus the low-level raw escape
  124. hatches, leaving: `get_help`, `check_coros_auth`, `get_daily_metrics`,
  125. `get_sleep_data`, `list_activities`, `get_activity_detail`,
  126. `list_workout_templates`, `list_training_plans`, `list_planned_activities`,
  127. `list_exercises`, `sync_coros_data`, `get_cache_status`. A smaller tool
  128. list also improves tool-calling reliability of non-frontier models.
  129. Default: `full` (all 26 tools).
  130. - `COROS_MCP_HIDE_AUTH_TOOLS=1` removes the two `authenticate_*` tools so
  131. your password can never travel through the model context or agent logs.
  132. Authentication then happens exclusively via the `COROS_EMAIL` /
  133. `COROS_PASSWORD` env auto-login (or tokens stored beforehand with
  134. `coros-mcp auth`).
  135. All tools additionally carry MCP `readOnlyHint` / `destructiveHint`
  136. annotations, so agent harnesses that honor them can require confirmation
  137. for write actions.
  138. ---
  139. ## Tool Reference
  140. ### `authenticate_coros`
  141. Log in with your Coros credentials. The auth token is stored securely in your system keyring (or an encrypted file as fallback).
  142. ```json
  143. { "email": "you@example.com", "password": "yourpassword", "region": "eu" }
  144. ```
  145. Returns: `authenticated`, `user_id`, `region`, `message`
  146. ### `authenticate_coros_mobile`
  147. Authenticate with the Coros mobile API only. This is mainly useful if you need to restore sleep-data access without redoing full web authentication.
  148. ```json
  149. { "email": "you@example.com", "password": "yourpassword", "region": "eu" }
  150. ```
  151. Returns: `authenticated`, `user_id`, `region`, `message`
  152. ### `check_coros_auth`
  153. Check whether valid web and mobile tokens are stored and how long the web token remains valid.
  154. ```json
  155. {}
  156. ```
  157. Returns: `authenticated`, `user_id`, `region`, `expires_in_hours`, `mobile_authenticated`, `mobile_token_status`
  158. ### `get_daily_metrics`
  159. Fetch daily metrics for a configurable number of weeks (default: 4).
  160. ```json
  161. { "weeks": 4 }
  162. ```
  163. Returns: `records` (list), `count`, `date_range`
  164. Each record includes:
  165. | Field | Source | Description |
  166. |-------|--------|-------------|
  167. | `date` | — | Date (YYYYMMDD) |
  168. | `avg_sleep_hrv` | dayDetail | Nightly HRV (RMSSD ms) |
  169. | `baseline` | dayDetail | HRV rolling baseline |
  170. | `rhr` | dayDetail | Resting heart rate (bpm) |
  171. | `training_load` | dayDetail | Daily training load |
  172. | `training_load_ratio` | dayDetail | Acute/chronic training load ratio |
  173. | `tired_rate` | dayDetail | Fatigue rate |
  174. | `ati` / `cti` | dayDetail | Acute / chronic training index |
  175. | `distance` / `duration` | dayDetail | Distance (m) / duration (s) |
  176. | `vo2max` | analyse (merge) | VO2 Max (last ~28 days) |
  177. | `lthr` | analyse (merge) | Lactate threshold heart rate (bpm) |
  178. | `ltsp` | analyse (merge) | Lactate threshold pace (s/km) |
  179. | `stamina_level` | analyse (merge) | Base fitness level |
  180. | `stamina_level_7d` | analyse (merge) | 7-day fitness trend |
  181. ### `get_sleep_data`
  182. Fetch nightly sleep stage data for a configurable number of weeks (default: 4).
  183. ```json
  184. { "weeks": 4 }
  185. ```
  186. Returns: `records` (list), `count`, `date_range`
  187. Each record includes:
  188. | Field | Description |
  189. |-------|-------------|
  190. | `date` | Date (YYYYMMDD) — the morning after the sleep |
  191. | `total_duration_minutes` | Total sleep in minutes |
  192. | `phases.deep_minutes` | Deep sleep |
  193. | `phases.light_minutes` | Light sleep |
  194. | `phases.rem_minutes` | REM sleep |
  195. | `phases.awake_minutes` | Time awake during the night |
  196. | `phases.nap_minutes` | Daytime nap time (null if none) |
  197. | `avg_hr` | Average heart rate during sleep |
  198. | `min_hr` | Minimum heart rate during sleep |
  199. | `max_hr` | Maximum heart rate during sleep |
  200. | `quality_score` | Sleep quality score (null if not computed) |
  201. > **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.
  202. ### `list_activities`
  203. List activities for a date range.
  204. ```json
  205. { "start_day": "20260101", "end_day": "20260305", "page": 1, "size": 30 }
  206. ```
  207. Returns: `activities` (list), `total_count`, `page`
  208. Each activity includes: `activity_id`, `name`, `sport_type`, `sport_name`, `start_time`, `end_time`, `duration_seconds`, `distance_meters`, `avg_hr`, `max_hr`, `calories` (in cal — divide by 1000 for kcal), `training_load`, `avg_power`, `normalized_power`, `elevation_gain`
  209. ### `get_activity_detail`
  210. Fetch full detail for a single activity. Requires the `sport_type` from `list_activities`.
  211. ```json
  212. { "activity_id": "469901014965714948", "sport_type": 200 }
  213. ```
  214. Returns full activity data including laps, HR zones, power zones, and all sport-specific metrics.
  215. > **Note:** Large time-series arrays (`graphList`, `frequencyList`, `gpsLightDuration`) are stripped from the response to keep it manageable.
  216. ### `list_workout_templates`
  217. List reusable workout templates saved in the Coros library.
  218. ```json
  219. {}
  220. ```
  221. Returns: `workouts` (list), `count`
  222. Each entry includes: `id`, `name`, `sport_type`, `sport_name`, `estimated_time_seconds`, `exercise_count`, `exercises` (list of steps with `name`, `intensity_low`, `intensity_high`, `sets`, and exactly one duration key: `duration_seconds`, `distance_meters`, or `duration_open`)
  223. ### `save_workout_template`
  224. 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.
  225. > ⚠️ This persists to the library indefinitely. For a one-off workout for a specific date, use [`schedule_workout`](#schedule_workout) instead — it builds the workout inline and leaves no library entry.
  226. **Plain steps:**
  227. ```json
  228. {
  229. "name": "Sweet Spot 90min",
  230. "sport_type": 2,
  231. "steps": [
  232. {"name": "15:00 Warmup", "duration_minutes": 15, "intensity_low": 148, "intensity_high": 192},
  233. {"name": "20:00 Sweet Spot", "duration_minutes": 20, "intensity_low": 260, "intensity_high": 275},
  234. {"name": "5:00 Rest", "duration_minutes": 5, "intensity_low": 100, "intensity_high": 150},
  235. {"name": "20:00 Sweet Spot", "duration_minutes": 20, "intensity_low": 260, "intensity_high": 275},
  236. {"name": "30:00 Cooldown", "duration_minutes": 30, "intensity_low": 100, "intensity_high": 192}
  237. ]
  238. }
  239. ```
  240. **With repeat groups (intervals):**
  241. ```json
  242. {
  243. "name": "3×10min Sweet Spot",
  244. "sport_type": 2,
  245. "steps": [
  246. {"name": "Warmup", "duration_minutes": 10, "intensity_low": 150, "intensity_high": 200},
  247. {"repeat": 3, "steps": [
  248. {"name": "Sweet Spot", "duration_minutes": 10, "intensity_low": 265, "intensity_high": 285},
  249. {"name": "Recovery", "duration_minutes": 3, "intensity_low": 150, "intensity_high": 175}
  250. ]},
  251. {"name": "Cooldown", "duration_minutes": 11, "intensity_low": 150, "intensity_high": 200}
  252. ]
  253. }
  254. ```
  255. **Distance-based steps:** use `duration_meters` instead of `duration_minutes` for a step that should end at a real distance regardless of pace, e.g. `{"name": "1km @ 4:00/km", "duration_meters": 1000, "intensity_low": 235, "intensity_high": 245}` (pace in sec/km with `intensity_type: 3`).
  256. **Open (lap-press) steps:** use `duration_open: true` for a step with no clock and no distance cap — the watch shows no countdown and advances only when the athlete presses lap, e.g. `{"name": "Warm-up", "duration_open": true, "intensity_low": 120, "intensity_high": 150}`. Intensity bounds still show as a guide zone but never end the step. Because an open step's length is unknowable ahead of time, it counts toward neither `total_minutes` nor `distance_meters_total`, and the response carries a `warning` saying so.
  257. Exactly one of the three keys (`duration_minutes`, `duration_meters`, `duration_open`) per step.
  258. `sport_type`: `2` = Indoor Cycling (default), `200` = Road Bike
  259. Returns: `workout_id`, `name`, `total_minutes`, `distance_meters_total`, `steps_count`, `message`
  260. ### `save_strength_workout_template`
  261. Save a reusable strength workout **template** to the Coros library. Exercises must come from the Coros exercise catalogue.
  262. > ⚠️ This persists to the library indefinitely. For a one-off workout for a specific date, use [`schedule_strength_workout`](#schedule_strength_workout) instead — it builds the workout inline and leaves no library entry.
  263. ```json
  264. {
  265. "name": "Leg Circuit",
  266. "sets": 3,
  267. "exercises": [
  268. {
  269. "origin_id": "54",
  270. "name": "T1061",
  271. "overview": "sid_strength_squats",
  272. "target_type": 3,
  273. "target_value": 12,
  274. "rest_seconds": 45,
  275. "sets": 3,
  276. "weight_kg": 80
  277. },
  278. {
  279. "origin_id": "130",
  280. "name": "T1176",
  281. "overview": "sid_strength_plank",
  282. "target_type": 2,
  283. "target_value": 60,
  284. "rest_seconds": 30
  285. }
  286. ]
  287. }
  288. ```
  289. `target_type`: `2` = time in seconds, `3` = reps
  290. `sets` (per exercise, optional): consecutive sets of that exercise before moving on. Use this instead of duplicating the exercise entry. Defaults to 1.
  291. `sets` (top-level): full-circuit repetitions — repeats the entire exercise list. Defaults to 1.
  292. **Weight fields (per exercise, optional):**
  293. | Field | Description |
  294. |-------|-------------|
  295. | `weight_kg` | Prescribed weight in kg (e.g. `80`) |
  296. | `weight_lbs` | Prescribed weight in pounds (e.g. `176.4`) — mutually exclusive with `weight_kg` |
  297. - Omitting **both** fields renders the exercise as **Bodyweight** in the Coros app.
  298. - Setting `weight_kg: 0` renders as **"0.00 kg"** — distinct from Bodyweight.
  299. - For dumbbell exercises, the weight is per hand by convention (the app shows a single value).
  300. - kg and lbs can be mixed across exercises within the same workout.
  301. Returns: `workout_id`, `name`, `sets`, `exercise_count`
  302. ### `delete_workout_template`
  303. Delete a saved workout template from the Coros library.
  304. ```json
  305. { "workout_id": "476023839273435149" }
  306. ```
  307. The `workout_id` comes from `list_workout_templates`.
  308. Returns: `deleted`, `workout_id`, `message`
  309. ### `list_planned_activities`
  310. List planned activities from the Coros training calendar.
  311. ```json
  312. { "start_day": "20260309", "end_day": "20260316" }
  313. ```
  314. Returns: `schedule` (dict with `entities` and `programs` sub-lists), `count` (number of scheduled entities), `date_range`
  315. ### `schedule_workout`
  316. 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.
  317. Same parameters as [`save_workout_template`](#save_workout_template), plus `happen_day` (YYYYMMDD) and an optional `sort_no` (order within the day).
  318. ```json
  319. {
  320. "name": "Z2 Recovery",
  321. "happen_day": "20260312",
  322. "sport_type": 2,
  323. "steps": [
  324. {"name": "Easy spin", "duration_minutes": 60, "intensity_low": 150, "intensity_high": 200}
  325. ]
  326. }
  327. ```
  328. Returns: `scheduled`, `name`, `happen_day`, `total_minutes`, `steps_count`, `response`
  329. ### `schedule_strength_workout`
  330. 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.
  331. Same parameters as [`save_strength_workout_template`](#save_strength_workout_template), plus `happen_day`.
  332. ```json
  333. {
  334. "name": "Push Day",
  335. "happen_day": "20260312",
  336. "sets": 1,
  337. "exercises": [ ... ]
  338. }
  339. ```
  340. Returns: `scheduled`, `name`, `happen_day`, `sets`, `exercise_count`, `response`
  341. ### `schedule_workout_template`
  342. Schedule an existing library template on a calendar day.
  343. ```json
  344. { "workout_id": "1234567890", "happen_day": "20260312", "sort_no": 1 }
  345. ```
  346. The `workout_id` comes from `list_workout_templates`. For one-off workouts that don't need a library entry, use [`schedule_workout`](#schedule_workout) or [`schedule_strength_workout`](#schedule_strength_workout) instead.
  347. Returns: `scheduled`, `workout_id`, `happen_day`, `response`
  348. ### `remove_scheduled_workout`
  349. Remove a scheduled workout from the Coros training calendar.
  350. ```json
  351. {
  352. "plan_id": "987654321",
  353. "id_in_plan": "1234567890",
  354. "plan_program_id": "1234567890"
  355. }
  356. ```
  357. `plan_id`, `id_in_plan`, and `plan_program_id` come from `list_planned_activities`. If `plan_program_id` is missing, you can usually reuse `id_in_plan`.
  358. Returns: `removed`, `plan_id`, `id_in_plan`
  359. ### `list_exercises`
  360. List the Coros exercise catalogue for a sport type. Default `sport_type=4` returns strength exercises.
  361. ```json
  362. { "sport_type": 4 }
  363. ```
  364. Returns: `exercises` (list), `count`, `sport_type`
  365. ### `sync_coros_data`
  366. Backfill all data into the local SQLite cache for a date range. After the first full sync, `get_daily_metrics`, `get_sleep_data`, and `list_activities` serve historical data from cache and only fetch the incremental tail from the API.
  367. ```json
  368. { "start_day": "20230101", "end_day": "20260514" }
  369. ```
  370. Both parameters are optional and default to two years ago / today respectively. For large ranges (> 6 months) prefer the CLI:
  371. ```bash
  372. coros-mcp sync --from 20230101
  373. ```
  374. Returns: `daily` (records synced), `sleep` (records synced), `activities` (records synced), `errors` (list), `cache` (coverage summary)
  375. ### `get_cache_status`
  376. Show what data is currently stored in the local SQLite cache.
  377. ```json
  378. {}
  379. ```
  380. Returns per data type: `count`, `from` (earliest date), `to` (latest date). Also includes `db_path`.
  381. ---
  382. ## Requirements
  383. - Python ≥ 3.11
  384. - A Coros account (Training Hub)
  385. ---
  386. ## Project Structure
  387. ```
  388. coros-mcp/
  389. ├── coros_mcp/
  390. │ ├── server.py # MCP server with tool definitions
  391. │ ├── coros_api.py # Coros API client (auth, requests, parsers)
  392. │ ├── models.py # Pydantic data models
  393. │ ├── cli.py # CLI entry point (serve, auth, sync, cache-status, …)
  394. │ ├── auth/ # Token storage (keyring + encrypted file fallback)
  395. │ └── cache/ # SQLite cache layer (store, sync, utils)
  396. ├── tests/ # pytest test suite
  397. ├── pyproject.toml # Project metadata & dependencies
  398. └── docs/
  399. └── mobile-token.md # Mobile API token background (legacy reference)
  400. ```
  401. ## Dependencies
  402. - [fastmcp](https://github.com/jlowin/fastmcp) — MCP framework
  403. - [httpx](https://www.python-httpx.org/) — Async HTTP client
  404. - [pydantic](https://docs.pydantic.dev/) — Data validation
  405. - [cryptography](https://cryptography.io/) — AES encryption (mobile API auth + token file)
  406. - [keyring](https://github.com/jaraco/keyring) — Secure token storage
  407. - [python-dotenv](https://github.com/theskumar/python-dotenv) — `.env` support
  408. ## Disclaimer
  409. This project uses the **unofficial** Coros Training Hub API. The API may change at any time without notice. Use at your own risk.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.