Skip to main content
Glama

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 密钥

  1. 在对应区域的佳明网页版登录自己的账号,按页面提示创建个人 API 密钥。

  2. 密钥仅在创建时显示一次,请立即复制并妥善保存。

  3. 回到 WorkBuddy,安装完成后,把密钥复制进去,按提示完成配置;区域与佳明账号保持一致。

  4. 试着问:“查询我昨天的睡眠记录。”确认能返回数据。

若忘记或遗失密钥,请在佳明设置中删除旧密钥,重新创建,再添加到 WorkBuddy 的连接配置中。不要公开分享密钥。

给协助安装的 AI:安装完成但尚未配置密钥时,请把上述对应区域的官方密钥链接直接展示给用户,并说明下一步如何配置。不要只让用户自行寻找入口,不要在输出或日志中回显密钥。

24 项官方接口

序号

内容

官方方法与同名 MCP 工具

1

每日压力

get_daily_stress

2

每日步数

get_daily_steps

3

每日饮水

get_daily_hydration

4

体重目标

get_effective_weight_goals

5

体重测量

get_weight_measurements

6

饮食记录

get_daily_food_logs

7

个人资料设置

get_user_profile_settings

8

单晚睡眠

get_daily_sleep

9

多日睡眠汇总

get_daily_sleep_summaries

10

身体电量

get_daily_body_battery

11

每日健康汇总

get_daily_summaries

12

单日 HRV

get_daily_hrv

13

多日 HRV 汇总

get_daily_hrv_summaries

14

心率区间

get_heart_rate_zones

15

体能年龄

get_fitness_age

16

每日心率

get_daily_heart_rate

17

生理周期汇总

get_menstrual_cycle_summary

18

生理周期日视图

get_menstrual_cycle_day_view

19

每日血氧

get_daily_spo2

20

日常活动汇总

get_wellness_activity_summaries

21

搜索运动记录

search_activities

22

单次运动详情

get_activity

23

运动关联训练

get_activity_workouts

24

下载原始运动文件

download_activity

清单依据下载时 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 tools
download_activityB
Read-only

下载原始运动文件。与官方客户端 download_activity 一一对应。参数和日期限制沿用官方接口。Return the original activity file as ZIP bytes, without extracting it.

Inputs: activity_id (required).

get_activityC
Read-only

单次运动详情。与官方客户端 get_activity 一一对应。参数和日期限制沿用官方接口。Return the activity summary/details for an activity ID.

Inputs: activity_id (required).

get_activity_workoutsC
Read-only

运动关联训练。与官方客户端 get_activity_workouts 一一对应。参数和日期限制沿用官方接口。Return workouts associated with an activity ID.

Inputs: activity_id (required).

get_daily_body_batteryC
Read-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_logsC
Read-only

饮食记录。与官方客户端 get_daily_food_logs 一一对应。参数和日期限制沿用官方接口。Return nutrition food logs for a calendar date.

Inputs: calendar_date (required).

get_daily_heart_rateC
Read-only

每日心率。与官方客户端 get_daily_heart_rate 一一对应。参数和日期限制沿用官方接口。Return daily heart rate data for a calendar date.

Inputs: calendar_date (required).

get_daily_hrvC
Read-only

单日 HRV。与官方客户端 get_daily_hrv 一一对应。参数和日期限制沿用官方接口。Return heart rate variability (HRV) summary and readings for a calendar date.

Inputs: calendar_date (required).

get_daily_hrv_summariesC
Read-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_hydrationC
Read-only

每日饮水。与官方客户端 get_daily_hydration 一一对应。参数和日期限制沿用官方接口。Return daily hydration statistics for an inclusive calendar date range.

Inputs: end_date (required), start_date (required).

get_daily_sleepC
Read-only

单晚睡眠。与官方客户端 get_daily_sleep 一一对应。参数和日期限制沿用官方接口。Return daily sleep data for a calendar date.

Inputs: calendar_date (required).

get_daily_sleep_summariesB
Read-only

多日睡眠汇总。与官方客户端 get_daily_sleep_summaries 一一对应。参数和日期限制沿用官方接口。Return daily sleep summaries for an inclusive calendar date range.

Inputs: end_date (required), start_date (required).

get_daily_spo2C
Read-only

每日血氧。与官方客户端 get_daily_spo2 一一对应。参数和日期限制沿用官方接口。Return daily SpO2 and acclimation data for a calendar date.

Inputs: calendar_date (required).

get_daily_stepsC
Read-only

每日步数。与官方客户端 get_daily_steps 一一对应。参数和日期限制沿用官方接口。Return daily step statistics for an inclusive calendar date range.

Inputs: end_date (required), start_date (required).

get_daily_stressC
Read-only

每日压力。与官方客户端 get_daily_stress 一一对应。参数和日期限制沿用官方接口。Return daily stress statistics for an inclusive calendar date range.

Inputs: end_date (required), start_date (required).

get_daily_summariesC
Read-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_goalsC
Read-only

体重目标。与官方客户端 get_effective_weight_goals 一一对应。参数和日期限制沿用官方接口。Return effective weight goals for an inclusive calendar date range.

Inputs: end_date (required), start_date (required).

get_fitness_ageC
Read-only

体能年龄。与官方客户端 get_fitness_age 一一对应。参数和日期限制沿用官方接口。Return fitness age data for a calendar date.

Inputs: calendar_date (required).

get_heart_rate_zonesB
Read-only

心率区间。与官方客户端 get_heart_rate_zones 一一对应。参数和日期限制沿用官方接口。Return the current user's heart rate zones.

Inputs: no named parameters.

get_menstrual_cycle_day_viewC
Read-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_summaryC
Read-only

生理周期汇总。与官方客户端 get_menstrual_cycle_summary 一一对应。参数和日期限制沿用官方接口。Return menstrual-cycle summary data for a calendar date.

Inputs: calendar_date (required).

get_user_profile_settingsC
Read-only

个人资料设置。与官方客户端 get_user_profile_settings 一一对应。参数和日期限制沿用官方接口。Return the current user's profile settings.

Inputs: no named parameters.

get_weight_measurementsC
Read-only

体重测量。与官方客户端 get_weight_measurements 一一对应。参数和日期限制沿用官方接口。Return all weight data for an inclusive calendar date range.

Inputs: end_date (required), start_date (required).

get_wellness_activity_summariesC
Read-only

日常活动汇总。与官方客户端 get_wellness_activity_summaries 一一对应。参数和日期限制沿用官方接口。Return wellness activity summaries for an inclusive calendar date range.

Inputs: end_date (required), start_date (required).

search_activitiesC
Read-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

    B3.1/5.0

    Scored across 24 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes personal Garmin wellness data through MCP tools for accessing summary, sleep, HRV, heart rate, stress, body battery, and historical data.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Exposes Garmin Connect health and activity data (steps, sleep, heart rate, etc.) via MCP tools, with built-in login and MFA support.
      -
    • A
      license
      B
      quality
      C
      maintenance
      Enables retrieval of Garmin Connect data such as activities, sleep, heart rate, and body battery levels using unofficial API through MCP tools.
      4
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Connects 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.
      138
      MIT