coros-additional-mcp

English | 中文

A Node.js 20+ TypeScript library and stdio MCP server for the unofficial COROS Training Hub API. It supports account/activity APIs and FIT/TCX uploads to the region-appropriate AWS S3 or mainland-China Aliyun OSS bucket.

A complement to the official COROS MCP

This project is a complement to the official COROS MCP endpoint and coroslab/COROS-MCP. It adds the one capability the official server does not provide: creating/importing an activity through activity/fit/import. The official MCP's activity tools are read-only (querySportRecords, getActivityDetail, and downloadActivityFitFiles); its write tools cover workouts and training plans. Run both servers side by side: use the official MCP for activity reads, workouts, and training plans, and use this server for activity uploads.

The two servers authenticate separately: sign in to the official MCP as its documentation describes, and bridge a Training Hub browser session here with coros-auth import-token.

Related MCP server: Coros MCP Server

Verification status

Install and build

npm install
npm run build

Library

import { CorosClient } from "coros-additional-mcp";

const client = new CorosClient(undefined, {
  accessToken: process.env.COROS_ACCESS_TOKEN!,
  region: "en",
});
const session = await client.resolveSession();
const result = await client.uploadActivity(fitBytes, "activity.fit", session.userId, { timezone: 32 });
console.log(result.importId, result.status, result.success);

resolveSession() validates an existing Training Hub browser token with getAccount() and uses its regionId (1 Americas, 2 mainland China, 3 Europe) to select the API host and storage configuration. Password login remains available through new CorosClient({ email, password }).login(), but it is an opt-in compatibility fallback.

timezone is measured in 15-minute units (32 means UTC+8). When omitted, it is calculated from the machine's current timezone.

MCP server

The coros-additional-mcp binary uses stdio and never returns a password or access token. The recommended setup stores only a browser session token in ~/.coros-additional-mcp/session.json; its directory is mode 0700 and the file is mode 0600.

Authenticate once by bridging the session token from a signed-in browser:

coros-auth import-token --region en
# Paste CPL-coros-token at the hidden stdin prompt.
coros-auth status

Credential priority is COROS_ACCESS_TOKEN → COROS_TOKEN_FILE → default token file → email/password. Authentication is lazy: the server starts and lists all tools with no credentials, while authenticated tools validate or log in on first use. check_coros_auth reports authSource, region, and user ID without printing or validating the token.

The server registers activity tools and a two-lane migration ledger. The ledger does not talk to Garmin or COROS by itself. Pair it with dsh-plugin-garmin-connect: that plugin downloads a Garmin FIT, and this server uploads it to COROS. Progress for the two directions is stored separately in ~/.coros-additional-mcp/migration.json.

• check_coros_auth — report auth source, in-memory login state, region, and user ID (never the token).

• upload_activity — upload an absolute local .fit/.tcx file or base64 content. Files are limited to 50 MB. An import status other than 2 means it may still be processing; query list_import_jobs.

• list_import_jobs — list recent activity import jobs.

• delete_import_job — remove an import job by ID.

• download_activity — download one activity as FIT, TCX, GPX, KML, or CSV. labelId and sportType come from list_activities. The file is written locally with mode 0600; the tool returns the path, not the bytes.

• list_activities — check that a newly uploaded activity appeared, and look up the labelId needed for download. For routine activity queries, use the official MCP's querySportRecords tool instead.

• migration_status / migration_enqueue / migration_next / migration_record — queue ids, take one due step, and record it. A success waits 45–85 seconds. A failure backs off from 30 seconds, doubling each attempt, capped at 15 minutes. Do not upload a second file while migration_next says to wait.

• migration_locate_garmin_fit — resolve {activityId}.fit under GARMIN_FIT_DOWNLOAD_DIR after the Garmin plugin downloads it.

Getting CPL-coros-token from the browser

The token is never passed as a command-line argument, and the CLI verifies it before saving:

1. Sign in on the official Training Hub: training.coros.com internationally, trainingcn.coros.com in mainland China, or trainingeu.coros.com in Europe.

2. Open DevTools (F12 or Inspect) and choose Application in Chrome/Edge, or Storage in Firefox.

3. Expand Cookies, then select the Training Hub origin.

4. Find CPL-coros-token and copy only its value. CPL-coros-region maps as 1=en, 2=cn, 3=eu.

5. Run coros-auth import-token --region en (replace the region when needed), paste at the hidden prompt, and press Enter. The CLI verifies the token before saving it and never prints it.

Claude Code configuration

After importing the token, no secrets are needed in .mcp.json:

{
  "mcpServers": {
    "coros": {
      "command": "npx",
      "args": ["-y", "coros-additional-mcp"]
    }
  }
}

Codex configuration

Add this server to your Codex MCP configuration:

[mcp_servers.coros]
command = "npx"
args = ["-y", "coros-additional-mcp"]

For a checked-out repository, replace npx and its arguments with the absolute path to dist/mcp/index.js after running npm run build.

Attribution

This project is a derivative of Pinta365/coros (revision 240ac18), Copyright (c) 2026 Pinta365, used under the MIT License — see LICENSE. That source is retained under src/coros/, adapted from Deno-first TypeScript to a Node.js 20+ package.

src/coros/md5.ts carries the MD5 implementation from the Deno standard library, as vendored by Pinta365/coros and changed only in formatting, exported wrappers, and a narrowed parameter type. MD5 has no Web Crypto equivalent, so a userland implementation is required.

Big thanks to XiaoSiHwang (四哥), whose garmin-sync-coros worked out the mainland-China upload path first. This project follows that approach and reimplements it in TypeScript — the code here is written from scratch, not copied.

The credential handling here follows the security design of dsh-plugin-garmin-connect: the password stays on the vendor's own sign-in page, only a session token is persisted, the session file is owner-only (0700 directory, 0600 file) and written atomically, and tokens never reach command-line arguments, logs, or error messages.