Garmin MCP
Integrates with Garmin's official personal API to expose 24 read-only health and fitness data tools, including daily stress, steps, hydration, weight, food logs, sleep, body battery, HRV, heart rate, SpO2, menstrual cycle, wellness summaries, and activity search/details/workout/file downloads.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Garmin MCP How did I sleep last night, and what was my HRV?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Garmin MCP · 纯官方个人 API 版 v0.1.0
第三方 MCP 封装,不是 Garmin 官方产品。仅使用 Garmin 官方个人 API 客户端的 24 项专用数据接口。已移除账号密码登录、MFA、登录令牌导入及全部高级模式依赖。
实测情况
维护者已在 WorkBuddy 中实际安装,并确认可以使用。24 项接口依据官方 SDK 对齐,不代表已经逐项完成实测。本项目不是 Garmin 官方产品,也不代表获得官方认可。
Related MCP server: garmin-mcp
安装到 WorkBuddy
已在 WorkBuddy 手机 App 端实测可安装使用。将安装链接或 ZIP 发给 WorkBuddy,告诉它“帮我安装”。让其按以下方式安装:让其从解压目录执行 uv sync --locked --no-dev --python 3.12,不要重新从旧仓库安装。项目默认使用清华 PyPI 镜像。
配置 MCP 时,运行解压目录下 .venv/bin/garmin-mcp(Windows 为 .venv/Scripts/garmin-mcp.exe)。设置 GARMIN_PERSONAL_API_KEY 和 GARMIN_REGION=cn。需要保存密钥时可执行 .venv/bin/garmin-mcp-login --region cn,输入会隐藏。
密钥只显示一次,请安全保存。遗失时去佳明设置撤销旧密钥、重新创建并更新。第一次安装仍需准备 Python 3.12 与 uv,下载速度取决于实际运行环境。
安装完成后:获取并添加个人 API 密钥
如果你使用中国区账号,请打开佳明官方页面: 中国区:创建个人 API 密钥
国际区账号请使用: 国际区:创建个人 API 密钥
在对应区域的佳明网页版登录自己的账号,按页面提示创建个人 API 密钥。
密钥仅在创建时显示一次,请立即复制并妥善保存。
回到 WorkBuddy,安装完成后,把密钥复制进去,按提示完成配置;区域与佳明账号保持一致。
试着问:“查询我昨天的睡眠记录。”确认能返回数据。
若忘记或遗失密钥,请在佳明设置中删除旧密钥,重新创建,再添加到 WorkBuddy 的连接配置中。不要公开分享密钥。
给协助安装的 AI:安装完成但尚未配置密钥时,请把上述对应区域的官方密钥链接直接展示给用户,并说明下一步如何配置。不要只让用户自行寻找入口,不要在输出或日志中回显密钥。
24 项官方接口
序号 | 内容 | 官方方法与同名 MCP 工具 |
1 | 每日压力 |
|
2 | 每日步数 |
|
3 | 每日饮水 |
|
4 | 体重目标 |
|
5 | 体重测量 |
|
6 | 饮食记录 |
|
7 | 个人资料设置 |
|
8 | 单晚睡眠 |
|
9 | 多日睡眠汇总 |
|
10 | 身体电量 |
|
11 | 每日健康汇总 |
|
12 | 单日 HRV |
|
13 | 多日 HRV 汇总 |
|
14 | 心率区间 |
|
15 | 体能年龄 |
|
16 | 每日心率 |
|
17 | 生理周期汇总 |
|
18 | 生理周期日视图 |
|
19 | 每日血氧 |
|
20 | 日常活动汇总 |
|
21 | 搜索运动记录 |
|
22 | 单次运动详情 |
|
23 | 运动关联训练 |
|
24 | 下载原始运动文件 |
|
清单依据下载时 Garmin 官方 GitHub 的 GarminPersonalApiClient。不把认证、令牌刷新、通用 GET 计为额外数据项目;不会通过通用 GET 暴露未知端点。
JSON 数据直接返回,不做趋势计算、字段删减、日期截断、自动拆分或额外指标推断。参数与官方客户端一致,日期范围超限时返回官方错误。运动文件下载以 MCP 二进制资源(Base64 传输)提供,解码后与官方 ZIP 字节一致;客户端能否保存附件需实测。
安全与部署
个人密钥本身敏感,只读不等于没有隐私风险;查询结果会交给 AI 客户端处理。本服务按单人单账号设计。公网网页设置必须通过可信 HTTPS 代理使用,并设置独立 ADMIN_PASSWORD。不要把含凭证的兼容 URL 公开分享。未经全面安全审计,不承诺绝对安全。
网页可用 garmin-mcp-web 启动,提供个人密钥设置与 MCP 认证,不提供任何 Garmin 密码登录入口。
出处
开发过程:由维护者设计与维护,Claude Code 协助编写初版,Codex 协助修改与安全加固。保留源码中的 MIT 版权与许可声明。
官方客户端:https://github.com/garmin/connect-personal-api-python ,Garmin Ltd. 或其子公司,Apache-2.0;通过依赖安装,未修改其源码。
MCP Python SDK:https://github.com/modelcontextprotocol/python-sdk ,许可证以依赖发行版为准。
本次修改:移除账号模式,将 MCP 数据工具与官方 24 项方法一一对应,保留中国区切换和国内依赖镜像。
Garmin 个人 API 适用其个人使用条款。使用官方 API 不代表本项目获得 Garmin 官方认可。原有源代码许可不替代 API 使用条款。
v0.1.0 安全加固与更新
24 项官方数据接口与原始数据返回方式不变。本次更新涉及凭证与服务保护。
本地 WorkBuddy MCP 继续使用原命令及个人密钥。推荐在新解压目录安装,再更新命令路径并重启该 MCP,确认运行的是 0.1.0。
默认关闭带密钥的
/k/<secret>/mcp网址认证。远程连接使用/mcp和 Authorization 请求头。仅 ALLOW_URL_SECRET=1 时恢复旧网址方式;它仍可能被外部日志记录。Web 默认绑定 127.0.0.1。容器明确配置 HOST=0.0.0.0 供可信入口访问;公网使用 HTTPS 反向代理,并配置 PUBLIC_URL 和真实可信代理 IP。不要直接明文暴露凭证页面。
管理密码至少 12 位,不接受示例占位密码。管理 POST 要求同源 Origin。
凭证文件私有权限与原子写入,拒绝符号链接。POSIX 已测试;Windows ACL 尚需验证。磁盘凭证仍是明文文件,不是加密保险箱。
环境中的网络代理和 TLS 信任由主机管理员控制,请使用可信主机和代理。
删除本地凭证不等于撤销 Garmin 密钥。停用时应去佳明设置撤销。
附 SECURITY.md 和检查记录;本次检查不是独立渗透测试或绝对安全保证。
开发与 AI 协助
项目维护者:需求设计、测试与发布维护。
Claude Code(Anthropic):协助编写初版。
Codex(OpenAI):协助修改、接口对齐与安全加固。
以上为开发工具致谢,不代表 Anthropic、OpenAI 或 Garmin 对项目的官方认可。
Available Tools
24 toolsdownload_activityBRead-only
下载原始运动文件。与官方客户端 download_activity 一一对应。参数和日期限制沿用官方接口。Return the original activity file as ZIP bytes, without extracting it.
Inputs: activity_id (required).
get_activityCRead-only
单次运动详情。与官方客户端 get_activity 一一对应。参数和日期限制沿用官方接口。Return the activity summary/details for an activity ID.
Inputs: activity_id (required).
get_activity_workoutsCRead-only
运动关联训练。与官方客户端 get_activity_workouts 一一对应。参数和日期限制沿用官方接口。Return workouts associated with an activity ID.
Inputs: activity_id (required).
get_daily_body_batteryCRead-only
身体电量。与官方客户端 get_daily_body_battery 一一对应。参数和日期限制沿用官方接口。Return daily Body Battery data for an inclusive calendar date range.
Inputs: end_date (required), start_date (required), chunks.
get_daily_food_logsCRead-only
饮食记录。与官方客户端 get_daily_food_logs 一一对应。参数和日期限制沿用官方接口。Return nutrition food logs for a calendar date.
Inputs: calendar_date (required).
get_daily_heart_rateCRead-only
每日心率。与官方客户端 get_daily_heart_rate 一一对应。参数和日期限制沿用官方接口。Return daily heart rate data for a calendar date.
Inputs: calendar_date (required).
get_daily_hrvCRead-only
单日 HRV。与官方客户端 get_daily_hrv 一一对应。参数和日期限制沿用官方接口。Return heart rate variability (HRV) summary and readings for a calendar date.
Inputs: calendar_date (required).
get_daily_hrv_summariesCRead-only
多日 HRV 汇总。与官方客户端 get_daily_hrv_summaries 一一对应。参数和日期限制沿用官方接口。Return daily heart rate variability (HRV) summaries for an inclusive date range.
Inputs: end_date (required), start_date (required).
get_daily_hydrationCRead-only
每日饮水。与官方客户端 get_daily_hydration 一一对应。参数和日期限制沿用官方接口。Return daily hydration statistics for an inclusive calendar date range.
Inputs: end_date (required), start_date (required).
get_daily_sleepCRead-only
单晚睡眠。与官方客户端 get_daily_sleep 一一对应。参数和日期限制沿用官方接口。Return daily sleep data for a calendar date.
Inputs: calendar_date (required).
get_daily_sleep_summariesBRead-only
多日睡眠汇总。与官方客户端 get_daily_sleep_summaries 一一对应。参数和日期限制沿用官方接口。Return daily sleep summaries for an inclusive calendar date range.
Inputs: end_date (required), start_date (required).
get_daily_spo2CRead-only
每日血氧。与官方客户端 get_daily_spo2 一一对应。参数和日期限制沿用官方接口。Return daily SpO2 and acclimation data for a calendar date.
Inputs: calendar_date (required).
get_daily_stepsCRead-only
每日步数。与官方客户端 get_daily_steps 一一对应。参数和日期限制沿用官方接口。Return daily step statistics for an inclusive calendar date range.
Inputs: end_date (required), start_date (required).
get_daily_stressCRead-only
每日压力。与官方客户端 get_daily_stress 一一对应。参数和日期限制沿用官方接口。Return daily stress statistics for an inclusive calendar date range.
Inputs: end_date (required), start_date (required).
get_daily_summariesCRead-only
每日健康汇总。与官方客户端 get_daily_summaries 一一对应。参数和日期限制沿用官方接口。Return user daily summaries for an inclusive calendar date range.
Use the same start and end date for a single day. The response preserves the endpoint's object containing a data array, even for one day.
Inputs: end_date (required), start_date (required).
get_effective_weight_goalsCRead-only
体重目标。与官方客户端 get_effective_weight_goals 一一对应。参数和日期限制沿用官方接口。Return effective weight goals for an inclusive calendar date range.
Inputs: end_date (required), start_date (required).
get_fitness_ageCRead-only
体能年龄。与官方客户端 get_fitness_age 一一对应。参数和日期限制沿用官方接口。Return fitness age data for a calendar date.
Inputs: calendar_date (required).
get_heart_rate_zonesBRead-only
心率区间。与官方客户端 get_heart_rate_zones 一一对应。参数和日期限制沿用官方接口。Return the current user's heart rate zones.
Inputs: no named parameters.
get_menstrual_cycle_day_viewCRead-only
生理周期日视图。与官方客户端 get_menstrual_cycle_day_view 一一对应。参数和日期限制沿用官方接口。Return the menstrual-cycle day view for a calendar date.
Inputs: today_date (required), calendar_date (required).
get_menstrual_cycle_summaryCRead-only
生理周期汇总。与官方客户端 get_menstrual_cycle_summary 一一对应。参数和日期限制沿用官方接口。Return menstrual-cycle summary data for a calendar date.
Inputs: calendar_date (required).
get_user_profile_settingsCRead-only
个人资料设置。与官方客户端 get_user_profile_settings 一一对应。参数和日期限制沿用官方接口。Return the current user's profile settings.
Inputs: no named parameters.
get_weight_measurementsCRead-only
体重测量。与官方客户端 get_weight_measurements 一一对应。参数和日期限制沿用官方接口。Return all weight data for an inclusive calendar date range.
Inputs: end_date (required), start_date (required).
get_wellness_activity_summariesCRead-only
日常活动汇总。与官方客户端 get_wellness_activity_summaries 一一对应。参数和日期限制沿用官方接口。Return wellness activity summaries for an inclusive calendar date range.
Inputs: end_date (required), start_date (required).
search_activitiesCRead-only
搜索运动记录。与官方客户端 search_activities 一一对应。参数和日期限制沿用官方接口。Return summarized activities matching the supplied search filters.
Inputs: limit, start, end_date, start_date, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Each tool maps to a distinct Garmin metric endpoint (stress, steps, hydration, sleep, HRV, SpO2, etc.), so most selection is obvious. The main risk is the single-day vs. multi-day summary pairs like get_daily_sleep/get_daily_sleep_summaries and get_daily_hrv/get_daily_hrv_summaries, plus get_daily_summaries vs get_wellness_activity_summaries, which require reading descriptions to distinguish.
All names are snake_case verb_noun following the get_<resource> pattern that mirrors the official API endpoints. The two non-get verbs (search_activities, download_activity) are semantically appropriate for their actions and still fit the convention.
24 tools is at the heavy edge of the ideal range, but each corresponds to a distinct Garmin wellness/activity endpoint, so most earn their place. The single/summary duplication pairs push the count slightly higher than strictly necessary.
The surface covers a broad read-only slice of Garmin data (wellness metrics, sleep, HRV, activities, downloads, profile) with no dead ends for querying. Gaps exist for write operations, device lists, and broader activity/workout library browsing, but the read-oriented domain is largely handled.
Maintenance
Related MCP Connectors
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Unofficial Garmin Connect access: sleep, HRV, training, activities, workouts and weight.
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceExposes personal Garmin wellness data through MCP tools for accessing summary, sleep, HRV, heart rate, stress, body battery, and historical data.MIT
- FlicenseNot gradedqualityDmaintenanceExposes Garmin Connect health and activity data (steps, sleep, heart rate, etc.) via MCP tools, with built-in login and MFA support.-
- AlicenseBqualityCmaintenanceEnables retrieval of Garmin Connect data such as activities, sleep, heart rate, and body battery levels using unofficial API through MCP tools.4MIT
- AlicenseBqualityDmaintenanceConnects to Garmin Connect and exposes fitness and health data via 110+ tools for activities, health metrics, workouts, training analytics, and more to MCP-compatible clients.138MIT