Skip to main content
Glama

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+

  • uv

  • 一个 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 = 60

ChatGPT 桌面应用、Codex CLI 和 Codex IDE 扩展共享同一 Codex 主机的 MCP 配置。在 ChatGPT 桌面版中,您也可以打开 设置 → MCP 服务器 → 添加服务器,选择 STDIO,并使用相同的命令。添加后重启客户端,然后使用 /mcp 确认 garmin-cn 已连接。

ChatGPT 网页版不会读取本地 Codex MCP 配置。网页版使用需要单独托管的远程 MCP/插件,并配备多用户授权和隐私设计;这有意不在本项目的范围内。

工具

  • 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

每个工具都是只读且非破坏性的。日期范围上限为 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 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

    • F
      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.
      -
    • 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.
      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
      -