garmin-cn-mcp
Garmin Connect China MCP
一个面向中国区 Garmin Connect 账户的本地只读 MCP 服务器。每个 Garmin 客户端都被硬锁定到 garmin.cn;API 读取请求发送到 https://connectapi.garmin.cn,以及对应的中国区 SSO/DI 认证主机。
本项目通过 garminconnect 使用 Garmin Connect 的非官方消费者 Web API。它适合私人个人使用,当 Garmin 更改其服务时可能会失效,并且不能替代面向商业产品的经批准的 Garmin Health API。
环境要求
Python 3.12+
一个 Garmin Connect 中国区账户
Related MCP server: garmin-mcp
安装与认证
在此目录下执行:
uv sync
uv run garmin-cn-auth认证命令会直接在终端中提示输入邮箱、密码和 MFA 验证码。密码和 MFA 验证码永远不会成为 MCP 参数。可刷新的令牌默认存储在 ~/.config/garmin-cn-mcp/ 下,并设置为仅所有者可读权限。
请像对待密码一样对待该令牌目录。如果它可能已被复制,请删除该目录并从 Garmin 的账户/安全设置中撤销账户访问权限。
添加到 Codex / ChatGPT 桌面版
使用 Codex CLI:
codex mcp add garmin-cn -- \
uv --directory /absolute/path/to/garmincn-mcp run garmin-cn-mcp或者将其添加到 ~/.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 = 60ChatGPT 桌面应用、Codex CLI 和 Codex IDE 扩展共享同一 Codex 主机的 MCP 配置。在 ChatGPT 桌面版中,您也可以打开 设置 → MCP 服务器 → 添加服务器,选择 STDIO,并使用相同的命令。添加后重启客户端,然后使用 /mcp 确认 garmin-cn 已连接。
ChatGPT 网页版不会读取本地 Codex MCP 配置。网页版使用需要单独托管的远程 MCP/插件,并配备多用户授权和隐私设计;这有意不在本项目的范围内。
工具
get_connection_statusget_daily_summaryget_sleepget_heart_rateget_hrvget_training_readinessget_morning_training_readinessget_body_batterylist_activitiesget_activity_detailsget_activity_exercise_setsget_activity_supplementary
每个工具都是只读且非破坏性的。日期范围上限为 31 天,活动列表上限为 100 条结果。不暴露任何原始 API 路径或 Garmin 写入工具。
自定义令牌存储路径
为认证和 MCP 进程都设置 GARMIN_CN_TOKEN_STORE,或者向任一命令传递 --token-store。请将该路径放在 Git 仓库之外。
开发检查
uv sync --group dev
uv run pytest
uv run ruff check .
uv run mypy测试使用模拟的提供程序,绝不会联系 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
- FlicenseNot 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.-
- FlicenseAqualityDmaintenanceProvides read-only access to your Garmin Connect health data, including sleep, HRV, body battery, stress, training readiness, and activities, through an MCP server.14-
- 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-