garmin-cn-mcp
Provides read-only access to Garmin Connect China data, including daily summaries, sleep, heart rate, HRV, training readiness, body battery, and detailed activity records.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@garmin-cn-mcp What was my sleep and HRV for last night?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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+
A Garmin Connect China account
Related MCP server: garmin-mcp
Install and authenticate
From this directory:
uv sync
uv run garmin-cn-authThe 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-mcpOr 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 = 60The 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_statusget_daily_summaryget_sleepget_heart_rateget_hrvget_training_readinessget_morning_training_readinessget_body_batterylist_activitiesget_activity_detailsget_activity_exercise_setsget_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 mypyTests use fabricated providers and never contact Garmin.
Available Tools
12 toolsget_activity_detailsGet Garmin activity detailsBRead-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 setsARead-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 dataARead-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 BatteryARead-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 connectionARead-onlyIdempotent
Validate cached Garmin China authentication and return minimal account status.
Inputs: no named parameters. Returns: object
get_daily_summaryGet Garmin daily summaryBRead-onlyIdempotent
Get Garmin Connect China daily wellness and activity summary for YYYY-MM-DD.
Inputs: date (required). Returns: object
get_heart_rateGet Garmin heart rateARead-onlyIdempotent
Get Garmin Connect China daily heart-rate data for YYYY-MM-DD.
Inputs: date (required). Returns: object
get_hrvGet Garmin HRVARead-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 readinessARead-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 sleepARead-onlyIdempotent
Get Garmin Connect China sleep data for YYYY-MM-DD.
Inputs: date (required). Returns: object
get_training_readinessGet Garmin training readinessARead-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 activitiesARead-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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
Unofficial Garmin Connect access: sleep, HRV, training, activities, workouts and weight.
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Access COROS activity, training and health data, and manage training plans and workouts.
Your swim, bike and run training: readiness, HRV, sleep, workouts and race predictions. Read-only.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides 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 npmMIT
- FlicenseAqualityDmaintenanceProvides read-only access to your Garmin Connect health data, including sleep, HRV, body battery, stress, training readiness, and activities, through an MCP server.214-
- AlicenseCqualityDmaintenanceEnables users to access and analyze Garmin China fitness and health data, including activities, recovery, trends, and weather heat stress, through 55 tools.5524 PyPIMIT
- FlicenseNot gradedqualityCmaintenanceEnables 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-