garmin-connect-mcp

一个模块化、可测试的 Garmin Connect MCP Server

把 Garmin 手表里的睡眠、心率、压力、训练数据接入任何支持 MCP 的 AI 助手，并生成可视化的健康日报与周报。

目录

• 为什么选择它

• 功能一览

• 快速开始

• 接入 MCP 客户端

• 工具列表

• 健康报告

• 安全设计

• 测试

• 文档

• 来源说明

Related MCP server: Garmin Health MCP Server

为什么选择它

大多数 Garmin MCP 实现只是 API 的薄封装。本项目把重点放在工程质量上：

• 开箱即用 — 一条命令启动，14 个工具自动注册，无需真实账号即可用 mock 模式体验

• 报告即产品 — 不只是返回 JSON，还能产出带图表的日报/周报，直接打开就能看

• 安全边界清晰 — 只读设计、凭据脱敏、Token 目录保护，敏感数据永远不会出现在日志里

• 经得起验证 — 单元 + 集成 + 端到端三层测试，GitHub Actions 上验证 Python 3.10 至 3.13

功能一览

📊 14 个数据工具

个人资料、活动、步数、睡眠、压力、HRV、身体成分、训练状态、训练准备度、VO2max 趋势，只读安全。

📈 健康日报 / 周报

数据覆盖率、趋势分析、异常提示，输出 Markdown 或自包含 HTML+SVG 报告，零外部依赖。

🔐 双认证模式

账号密码或 Token 认证，支持 Garmin 中国区，凭据可通过环境变量或文件注入。

🧪 Mock 模式

GARMIN_MCP_MOCK=true 即可脱离真实账号运行，让 CI 和演示都不依赖外部服务。

快速开始

1. 安装

git clone https://github.com/JaJum/garmin-connect-mcp.git
cd garmin-connect-mcp
uv sync

2. 配置

在项目根目录创建 .env（或直接设置环境变量）：

GARMIN_EMAIL=your@email.com
GARMIN_PASSWORD=your-password
GARMIN_IS_CN=true          # 中国区账号必填

只想先试一试？设置 GARMIN_MCP_MOCK=true 即可跳过真实账号，用模拟数据体验全部功能。

3. 启动

uv run garmin-connect-mcp

启动日志会显示运行模式（mock / live）、区域和已注册的工具数量。

接入 MCP 客户端

以 Claude Desktop 的 claude_desktop_config.json 为例：

{
  "mcpServers": {
    "garmin-connect-mcp": {
      "command": "uv",
      "args": ["--directory", "C:/path/to/garmin-connect-mcp", "run", "garmin-connect-mcp"],
      "env": {
        "GARMIN_EMAIL": "your@email.com",
        "GARMIN_PASSWORD": "your-password",
        "GARMIN_IS_CN": "true"
      }
    }
  }
}

任何支持 MCP stdio 传输的客户端（Cursor、Windsurf 等）都可以用同样方式接入。

工具列表

健康报告

报告引擎会自动计算数据覆盖率、绘制趋势图并标记异常指标：

• 输出格式：Markdown，或自包含的 HTML+SVG（可直接分享，无需联网）

• 日报：单日睡眠、静息心率、HRV、压力、训练负荷、步数 + 趋势图

• 周报：7 天聚合、每日明细表、异常指标提示、数据质量评估

• 输出目录：默认项目下 reports/（已加入 .gitignore，健康数据不会被提交）

安全设计

• 只读工具集 — 不提供任何修改 Garmin 数据的操作

• 凭据脱敏 — 密码和 Token 永远不会出现在日志、报错或工具返回值中

• Token 目录保护 — 报告输出目录禁止指向 Token 存储位置

• 敏感文件隔离 — .env、Token 目录默认被 .gitignore 排除

• allowlist / denylist — 可按需过滤暴露给 MCP 客户端的工具

测试

默认测试不需要真实 Garmin 账号：

uv sync
uv run pytest tests/unit tests/integration

真实账号 E2E 测试默认跳过，需要时手动开启：

$env:RUN_GARMIN_E2E = "1"
uv run pytest tests/e2e

CI 会在 Python 3.10、3.11、3.12 和 3.13 上自动运行单元与集成测试。

文档

技术栈：Python 3.10+ · FastMCP · python-garminconnect · pytest · GitHub Actions

来源说明

本项目参考了 Taxuspt/garmin_mcp（MIT License）的模块化思路，但采用独立项目名、独立包结构和缩小后的工具范围。

免责声明：Garmin 是 Garmin Ltd. 的注册商标，Garmin Connect 的界面截图与产品图片的版权归 Garmin Ltd. 所有，此处仅用于说明本工具的数据来源。本项目为社区开发的第三方工具，与 Garmin Ltd. 无官方关联。

License

MIT