AI导哈

Garmin Connect API代理服务

通过Playwright浏览器模拟访问Garmin Connect API的服务，支持获取活动数据、健康指标、睡眠分析等运动健康数据。

  • by etweisberg
  • TypeScript
  • 本地部署
  • 45 星标
  • 更新于
在 GitHub 查看 etweisberg/garmin-connect-mcp

使用说明

garmin连接mcp

Garmin Connect的MCP服务器。从Claude Code或任何MCP客户端访问您的活动、健康统计数据、睡眠数据、FIT文件等。

为什么存在

2026年3月，Garmin更改了他们的认证API 加思 和 python garminconnect --用于以编程方式访问Garmin数据的两个最受欢迎的库。Garth已经 正式弃用Garmin添加了Cloudflare TLS指纹识别功能，可阻止所有非浏览器HTTP客户端（Node.js fetchpython requests, curl)从其API端点。

该项目通过无头Playwright浏览器路由所有API调用，继承真正的Chrome TLS指纹，从而解决了这一问题。身份验证使用从手动登录会话中捕获的浏览器Cookie。

安装

npm install -g @etweisberg/garmin-connect-mcp
npx playwright install chromium

然后用Claude Code注册：

claude mcp add garmin -- npx @etweisberg/garmin-connect-mcp

登录流程还需要Playwright MCP服务器：

claude mcp add playwright -- npx @playwright/mcp@latest

先决条件

  • Node.js 18+
  • Playwright MCP服务器（用于基于浏览器的登录）
  • 带有同步设备的Garmin Connect帐户

设置

1.登录

在Claude Code中，调用 garmin-login 工具。它将引导您通过：

  1. 在Playwright浏览器中打开Garmin Connect
  2. 手动登录
  3. 提取Cookie和CSRF令牌
  4. 将会话保存到 ~/.garmin-connect-mcp/session.json

2.验证

打电话给 check-session 用于确认身份验证工作的工具。

会话Cookie在几个小时后过期。当他们这样做时，重新运行登录流。

可用工具

会话和身份验证

工具 说明
garmin-login 返回Playwright MCP浏览器的登录说明
check-session 验证保存的会话是否仍处于活动状态
run-tests 返回测试计划以验证所有工具是否正常工作

活动

工具 说明
list-activities 按页码列出活动
get-activity 完整的活动总结（距离、持续时间、心率、卡路里）
get-activity-details 时间序列指标（HR、节奏、随时间推移的提升）
get-activity-splits 搭接/拆分数据
get-activity-hr-zones 心率区域时间细分
get-activity-polyline 全分辨率GPS轨迹
get-activity-weather 活动期间的天气状况
download-fit 下载原始FIT文件

日常健康

工具 说明
get-daily-summary 步数、卡路里、距离、强度分钟
get-daily-heart-rate 全天心率数据
get-daily-stress 全天的压力水平
get-daily-summary-chart 综合健康图表数据
get-daily-intensity-minutes 约会的强度分钟数
get-daily-movement 运动/活动数据
get-daily-respiration 呼吸速率数据

睡眠/身体电池/HRV

工具 说明
get-sleep 睡眠评分、持续时间、阶段、SpO2
get-body-battery 车身蓄电池充电/放电值
get-hrv 心率变异性数据

训练与恢复

工具 说明
get-training-readiness 训练准备度得分（睡眠、恢复、负荷）
get-sleep-stats 日期范围内的睡眠统计数据
get-hydration 每日水合作用/摄入量数据

体重/记录/健康状况

工具 说明
get-weight 日期范围内的重量测量
get-personal-records 所有个人历史记录
get-fitness-stats 按类型汇总的活动统计数据
get-vo2max 最新VO2最大估计值
get-hr-zones-config 心率区域边界
get-power-zones 适用于所有运动的动力区配置
get-user-profile 用户配置文件和设置

日历、目标和徽章

工具 说明
get-calendar 活动和事件月历
get-goals 当前、未来或过去的健身目标
get-badges 所有获得的徽章/成就
get-badge-leaderboard 连接中的徽章排行榜

锻炼

工具 说明
list-workouts 列出已保存的训练
get-workout 获取锻炼细节（步骤、分段）
create-workout 创建新的训练（热身、间歇、冷却）
schedule-workout 将锻炼安排到某个日期（同步到设备）
delete-workout 删除训练
download-workout-fit 将训练下载为FIT文件

建筑

Claude Code / MCP Client
        |
        | MCP (stdio)
        v
garmin-connect-mcp server
        |
        | page.evaluate(fetch(...))
        v
Headless Playwright Chromium
        |
        | HTTPS (real Chrome TLS fingerprint)
        v
connect.garmin.com/gc-api/*

所有API调用都是在无头Chromium浏览器上下文中通过 page.evaluate(fetch(...))。这继承了真正的Chrome TLS指纹，绕过了Cloudflare对非浏览器客户端的检测。

认证流程：Cookie+CSRF令牌从手动浏览器登录（通过Playwright MCP服务器）中捕获并存储在 ~/.garmin-connect-mcp/session.json。无头浏览器在启动时加载这些Cookie。

为什么不直接HTTP？ Cloudflare阻止Node.js fetchpython requests，甚至 curl 403。只接受来自真实浏览器TLS堆栈的请求。

发展

git clone https://github.com/etweisberg/garmin-connect-mcp.git
cd garmin-connect-mcp
npm install
npx playwright install chromium
npm run build

脚本

命令 描述
npm run build 编译TypeScript
npm run lint 运行ESLint
npm run format 带Prettier的格式
npm run typecheck 不发射的类型检查
npm test 运行集成测试（需要有效会话）

本地集成测试

独立测试套件(npm test)需要一个有效的Garmin会话，并达到真正的API。验证后在本地运行它：

npm test

贡献

  1. 创建特征分支 main
  2. 进行更改
  3. 运行检查：
    npm run lint
npm run format
npm run typecheck
npm run build
  4. 通过克劳德代码进行测试：验证更改的推荐方法是通过Claude Code。建成后，致电 run-tests MCP工具-它返回一个测试计划，针对现场Garmin API练习所有27个工具。告诉克劳德执行计划并报告结果。
  5. 打开一个PR main

CI在每个PR上运行lint、格式检查、类型检查和构建。集成测试仅在本地运行（它们需要Garmin身份验证，无法在CI中安全运行）。

释放

发布完全自动化。每次合并 main 触发发布工作流，该工作流：

  1. 运行CI（lint、format、typecheck、build）
  2. 更新补丁版本
  3. 以出处发布到npm
  4. 创建GitHub版本

无需手动修改版本或添加标签，只需合并您的PR即可。

许可证

AGPL-3.0

相关 MCP