Skip to main content
Glama

Garmin Connect China MCP

A local, read-only MCP server for a China-region Garmin Connect account. Every Garmin client is hard-locked to garmin.cn; API reads go to https://connectapi.garmin.cn and the corresponding China SSO/DI-auth hosts.

This uses Garmin Connect's unofficial consumer web API through garminconnect. It is suitable for private personal use, can break when Garmin changes its services, and is not a substitute for the approved Garmin Health API for commercial products.

Requirements

  • Python 3.12+

  • uv

  • A Garmin Connect China account

Related MCP server: garmin-mcp

Install and authenticate

From this directory:

uv sync
uv run garmin-cn-auth

The auth command prompts for email, password, and MFA directly in your terminal. Passwords and MFA codes never become MCP arguments. Refreshable tokens are stored by default under ~/.config/garmin-cn-mcp/ with owner-only permissions.

Treat that token directory like a password. If it may have been copied, remove it and revoke account access from Garmin's account/security settings.

Add to Codex / ChatGPT desktop

With Codex CLI:

codex mcp add garmin-cn -- \
  uv --directory /absolute/path/to/garmincn-mcp run garmin-cn-mcp

Or add this to ~/.codex/config.toml:

[mcp_servers.garmin-cn]
command = "uv"
args = [
  "--directory",
  "/absolute/path/to/garmincn-mcp",
  "run",
  "garmin-cn-mcp",
]
startup_timeout_sec = 20
tool_timeout_sec = 60

The ChatGPT desktop app, Codex CLI, and Codex IDE extension share MCP configuration for the same Codex host. In ChatGPT desktop you can also open Settings → MCP servers → Add server, select STDIO, and use the same command. Restart the client after adding it, then use /mcp to confirm garmin-cn is connected.

ChatGPT web does not read local Codex MCP configuration. Web use would require a separately hosted remote MCP/plugin with a multi-user authorization and privacy design; that is intentionally outside this project.

Tools

  • get_connection_status

  • get_daily_summary

  • get_sleep

  • get_heart_rate

  • get_hrv

  • get_training_readiness

  • get_morning_training_readiness

  • get_body_battery

  • list_activities

  • get_activity_details

  • get_activity_exercise_sets

  • get_activity_supplementary

Every tool is read-only and non-destructive. Date ranges are capped at 31 days and activity lists at 100 results. No raw API-path or Garmin write tool is exposed.

Custom token-store path

Set GARMIN_CN_TOKEN_STORE for both auth and MCP processes, or pass --token-store to either command. Keep the path outside a Git repository.

Development checks

uv sync --group dev
uv run pytest
uv run ruff check .
uv run mypy

Tests use fabricated providers and never contact Garmin.

Available Tools

12 tools
get_activity_detailsGet Garmin activity detailsB
Read-onlyIdempotent

Get detailed Garmin Connect China data for one positive activity ID.

Inputs: activity_id (required). Returns: object

get_activity_exercise_setsGet Garmin activity exercise setsA
Read-onlyIdempotent

Get per-set strength exercise details for one positive Garmin China activity ID, including set type, exercises, repetitions, weight, and duration when available.

Inputs: activity_id (required). Returns: object

get_activity_supplementaryGet Garmin activity supplementary dataA
Read-onlyIdempotent

Get cross-sport supplementary Garmin China data for one positive activity ID: canonical summary, laps/splits, typed splits, split summaries, weather, heart-rate zones, power zones, and gear. Unavailable sources are null with safe errors.

Inputs: activity_id (required). Returns: object

get_body_batteryGet Garmin Body BatteryA
Read-onlyIdempotent

Get Body Battery reports for an inclusive range of at most 31 days.

Inputs: start_date (required), end_date. Returns: result

get_connection_statusCheck Garmin China connectionA
Read-onlyIdempotent

Validate cached Garmin China authentication and return minimal account status.

Inputs: no named parameters. Returns: object

get_daily_summaryGet Garmin daily summaryB
Read-onlyIdempotent

Get Garmin Connect China daily wellness and activity summary for YYYY-MM-DD.

Inputs: date (required). Returns: object

get_heart_rateGet Garmin heart rateA
Read-onlyIdempotent

Get Garmin Connect China daily heart-rate data for YYYY-MM-DD.

Inputs: date (required). Returns: object

get_hrvGet Garmin HRVA
Read-onlyIdempotent

Get Garmin Connect China heart-rate variability data for YYYY-MM-DD.

Inputs: date (required). Returns: result

get_morning_training_readinessGet Garmin morning training readinessA
Read-onlyIdempotent

Get the morning Garmin Connect China Training Readiness snapshot for YYYY-MM-DD. The response includes Recovery Time when Garmin provides it.

Inputs: date (required). Returns: result

get_sleepGet Garmin sleepA
Read-onlyIdempotent

Get Garmin Connect China sleep data for YYYY-MM-DD.

Inputs: date (required). Returns: object

get_training_readinessGet Garmin training readinessA
Read-onlyIdempotent

Get all Garmin Connect China Training Readiness snapshots for YYYY-MM-DD. The response includes Recovery Time when Garmin provides it.

Inputs: date (required). Returns: result

list_activitiesList Garmin activitiesA
Read-onlyIdempotent

List recent Garmin China activities, or activities in an inclusive range of at most 31 days. Results are limited to 1-100.

Inputs: limit, end_date, start_date. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct data type or granularity: connection status, daily summary, sleep, heart rate, HRV, training readiness (overall vs. morning), body battery, activity list, and three activity-specific detail tools. No two tools have overlapping purposes; even the two training readiness tools are clearly differentiated by scope.

    Naming Consistency4/5

    Most tools follow a consistent 'get_' + noun pattern, with clear and descriptive names like get_sleep, get_hrv, and get_activity_details. The only deviation is 'list_activities' which uses 'list' instead of 'get', but this is a minor and sensible variation for a collection-returning operation.

    Tool Count5/5

    With 12 tools covering wellness metrics, activity lifecycle, and supplementary data, the count is well-scoped for a Garmin data retrieval server. Each tool serves a distinct purpose and none feel redundant or missing, making the set feel appropriately sized.

    Completeness4/5

    The server covers the major wellness and activity data categories from Garmin Connect China: daily summaries, sleep, heart rate, HRV, training readiness, body battery, activity lists, and detailed activity breakdowns. Minor gaps like stress or step-specific endpoints are likely covered by the daily summary, so the surface is quite complete for read-only access.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides read access to Garmin Connect health and training data (sleep, heart rate, stress, HRV, activities) and supports writes like creating workouts, editing activities, and exporting files.
      1,323 npm
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Provides read-only access to your Garmin Connect health data, including sleep, HRV, body battery, stress, training readiness, and activities, through an MCP server.
      2
      14
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables read-only access to Garmin Connect China account data, including activities, splits, sleep summaries, and available training metrics, so users can analyze running volume, laps, recent training, and race preparation through natural language.
      1
      -