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: health-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。