garmin-mcp
garmin-mcp
与你的 Garmin 数据对话。 一个只读的 MCP 服务器,让 Claude 和 ChatGPT 能够回答关于你训练数据的问题:活动、睡眠、HRV、Body Battery、训练状态、挑战排行榜——而且,与其他 Garmin MCP 服务器不同,还包括你的手表写入的原始 FIT 文件,其中包含 Connect-IQ 传感器通道(Stryd、Moxy/SmO2、CORE)。
You: How did my last long run compare to the same route in June?
You: Why is my training readiness so low this morning?
You: Where do I stand in the running challenge, and who is ahead of me?
You: Did my Stryd actually record power on Tuesday's session?它从不写入 Garmin Connect。每个工具都是只读的。
三种使用方式
1. 访客访问 | 2. 本地 | 3. 你自己的服务器 | |
状态 | 仅限邀请,计划开放访问 | 可用 | 可用 |
你需要 | 一份邀请 | Python 3.12 | 一台服务器、一个域名、Docker |
你运行 | 什么都不用 | 在你机器上运行服务器 | 为你和你的朋友运行服务器 |
适用于 | claude.ai、ChatGPT、Claude Desktop、Claude Code | Claude Desktop、Claude Code | 一切 |
设置 | 5 分钟 | 2 分钟 | 20 分钟 |
你的数据存放于 | 邀请你的实例上 | 仅在你的机器上 | 在你的服务器上 |
指南 |
1. 访客访问——唯一完全不需要基础设施的途径:打开邀请链接、创建账户、连接你的 Garmin,完成。与方式 3 一样,它适用于浏览器中的 claude.ai 和 ChatGPT——方式 2 不行,因为这两者都无法在你的电脑上启动程序。
访客访问尚未开放。 目前仅通过个人邀请向一小群测试者开放。计划提供公开的邀请申请方式——在那之前,方式 2 和 3 今天就可以使用。
2. 本地——没有任何数据离开你的机器,无需账户,无需服务器。你的 AI 客户端在需要时启动该进程。如果你本来就在使用 Claude Desktop 或 Claude Code,并且希望一切保持本地化,这是最佳选择。
3. 你自己的服务器——与访客访问背后相同的软件。为你自己运行,邀请任何你想邀请的人,拥有数据。参见 docs/self-hosting.md。
Related MCP server: Garmin Connect MCP
快速开始(本地)
uv tool install git+https://github.com/mskerwiderski/mcp-garmingarmin-mcp login登录时要求输入你的 Garmin 邮箱、密码,以及——如果你启用了——多因素验证码。它只存储 Garmin 的 OAuth 令牌,存放在 ~/.garmin-mcp/tokens.json 中,权限为 0600。你的密码永远不会被写入任何地方。
然后向你的客户端注册服务器:
claude mcp add garmin -- garmin-mcp serve开启一个新会话并提问。完整的分步指南,包括 Claude Desktop:docs/install-claude.md。
文档
指南 | 内容 |
获取邀请并使用它,从头到尾 | |
Claude Desktop、Claude Code、claude.ai、故障排除 | |
开发者模式、自定义连接器、故障排除 | |
问什么、返回什么、数字意味着什么 | |
每个工具、其参数和示例响应 | |
服务器设置、邀请、管理、升级 | |
设计决策,以及背后的 Garmin 特性 |
它能回答什么
活动——按运动和日期列出和筛选,Garmin 对单个活动的摘要,以及设备记录的同一活动,直接来自 FIT 文件。文件中任何通道的时间序列、池泳详情精确到单趟长度,以及哪些 Connect-IQ 传感器实际提供了数据。
健康——每天一次调用即可获得步数、静息心率、压力、Body Battery、带评分的睡眠阶段、HRV 状态和训练准备度。此外还有带负荷重点和 VO2max 的训练状态、身体成分和血压(按日期范围)。
趋势与计划——一次调用获取整整一个月的步数、Body Battery 和 VO2max,而不是每天一次;Garmin 的计划侧,包括训练计划锻炼和比赛,因此可以比较"计划了什么"和"实际发生了什么"。
你的位置——5 公里到马拉松的比赛预测、体能年龄、耐力和爬坡得分、终身总计,以及你的个人纪录和创造每项纪录的活动。
背景信息——你的阈值和心率区间、你的装备及其背后的活动、公里数、小时数和天数,以及你与朋友比拼的社交挑战,包括当前正在进行的挑战。
完整列表及参数参见 docs/tools.md。
为什么登录发生在你的机器上
Garmin 的 SSO 位于 Cloudflare 之后,自 2026 年 3 月起,Cloudflare 对来自数据中心 IP 的新登录以 429 或 403 响应。因此 garmin-mcp login 在你所在的位置运行。生成的 OAuth1 令牌有效期约为一年,并针对 connectapi.garmin.com 铸造访问令牌,因此登录之后不会再触及 sso.garmin.com。
托管服务器提供两种方式:登录表单(密码只使用一次,从不存储)以及粘贴来自 garmin-mcp export 的令牌块——当 Garmin 阻止服务器地址时,这是进入的方式。
须知
这使用 Garmin 的内部 Connect API——所有社区工具使用的同一个 API。没有面向个人的官方 API;Garmin 的 Health API 是合作伙伴计划。请仅将此用于你自己的账户,并将托管实例限制在你真正认识的人范围内:一台服务器上的所有账户对 Garmin 共享同一个地址。
响应刻意保持精简。Garmin 对每个活动返回数百个字段,时间序列有数千个点;所有内容都被投影到模型实际能使用的程度,流数据按通道以最小值/最大值/平均值重新采样。这不是装饰性的——原始负载会吞噬对话所需的上下文窗口。
开发
python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]".venv/bin/pytest103 个测试,无需网络访问——Garmin API 和 FIT 文件均被桩替换或合成。各部分的组合方式参见 docs/architecture.md。
许可证
MIT。参见 LICENSE。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Explore Garmin activity and health data with your AI assistant.
Garmin data in Claude: 135 tools — activities, sleep, HRV, training, workouts. Free, open source.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to query live Garmin Connect health and fitness data, including daily metrics, activities, sleep analysis, and trends via natural language.MIT
- FlicenseNot gradedqualityDmaintenanceEnables querying your Garmin Connect data including recent activities, detailed metrics, and daily stats through natural language.-
- AlicenseBqualityBmaintenanceEnables users to analyze their own Garmin Connect data—activities, sleep, HRV, Body Battery, training readiness—directly inside Claude Desktop.131,323 npm2MIT
- FlicenseAqualityDmaintenanceExposes your Garmin Connect data (activities, sleep, recovery, training status) to Claude in read-only mode.7-