Garmin Assistant (API edition) | Garmin 助手（API）版本

English version | 中文版本

English version

Use your own Garmin Personal API key to sync activity and health data locally, then ask an AI for running and recovery guidance with research citations and classic training frameworks.

No Garmin password. No shared accounts. No maintainer health data included. This independent project is not affiliated with or endorsed by Garmin.

Installation and user guide · Doubao / GPT / Claude setup · Updates and releases · References and verification · Changelog

First use

On first key setup or first interaction with the MCP, the assistant asks you to choose a language:

Welcome to Garmin Assistant! / 欢迎首次使用佳明助手！

Please choose your language / 请选择语言： 1. 中文　2. English

The choice is saved. Before selection, 1/2 selects a language; afterwards numbers select functions. Core menus, AI reply instructions and next-day reports support the selected language. Switch any time with garmin-assistant language en or garmin-assistant language zh. MCP cannot independently open a chat popup: the client presents the welcome at first interaction.

Quick installation — Windows PowerShell

Install Python 3.12+ and Git. Open PowerShell and run one line at a time:

git clone https://github.com/1838337544m-droid/garmin-assistant-api.git
cd garmin-assistant-api
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\garmin-assistant.exe init --timezone America/New_York

Set your own IANA timezone rather than copying the example blindly. Default is UTC. The initial goal is 10 km in under 60 minutes; change it with --goal-km and --goal-minutes. For complete Windows and macOS/Linux instructions, see the beginner user guide.

Run authentication separately:

.\.venv\Scripts\garmin-assistant.exe auth

At Garmin Personal API key (hidden):, paste your complete personal key once into PowerShell, then press Enter. No characters or asterisks appear; that is normal. Do not paste your key into an AI chat. First use then asks for 1 (Chinese) or 2 (English). "saved": true means the key was stored, not yet verified. Only after that, run:

.\.venv\Scripts\garmin-assistant.exe doctor --live

"garmin_status": "ok" confirms a successful Garmin read. Never paste the authentication and diagnostic commands together while the program is asking for the key.

Function menu

Core IDs 1–7 are stable. Hide them without removing the tools; say Show original function menu or 显示原有功能菜单 to restore them. Custom prompt workflows retain IDs starting at 100. They cannot override core tools and do not execute arbitrary third-party code.

AI client compatibility

Use client-config to generate paths for your actual installation. See the client guide. This release is not a hosted service, browser extension or prelisted official client application.

Data and evidence

• Initial sync requests 93 days; later syncs fill gaps and revisit overlapping dates. Missing records and failures are explicit.

• Next-day assessment syncs first. Research is refreshed after 7 days since the last successful search, or on demand.

• HRV, sleep, resting heart rate and recent running are interpreted against personal references. Unknown symptoms remain unknown.

• Reports cite classic fitness–fatigue, intensity-distribution and Daniels frameworks alongside applicable recent research.

• Newly retrieved papers require appraisal; they do not automatically rewrite training rules.

• Advice is provisional until the morning recheck, not medical clearance, an injury-risk probability or a fastest-progress guarantee.

Keys, settings, history, reports and custom menus are outside the source checkout, so code updates preserve them. Tool results go to your connected AI provider; choose a client that fits your privacy preferences.

Updates, extensions and self-check

Releases are published periodically. Users choose when to update; the project does not silently download and execute new code. See maintenance and rollback. MIT allows modification and forks; the immutable core is an official-release/extension compatibility contract, not a prohibition on editing open-source code.

python -m pip install -e ".[dev]"
python -m pytest -q
python scripts/check_release.py
python -m build

CI runs synthetic tests on Windows, macOS and Linux without personal Garmin credentials. See verification scope and self-check records.

Related MCP server: garmin-givemydata

中文版本

用自己的 Garmin Personal API 密钥，在本机同步运动与健康数据，让 AI 结合 长跑训练、恢复研究和经典模型提供有出处的建议。

不需要 Garmin 密码；不托管他人账号；不附带维护者的个人数据。 本项目独立开发，不隶属 Garmin。

安装与用户手册 · 豆包/GPT/Claude 接入 · 更新与发布 · 参考与验证范围 · 更新记录

英文快速入门

首次使用 / First use

首次保存密钥或在 AI 中首次调用本助手时，会看到：

欢迎首次使用佳明助手！
Welcome to Garmin Assistant!

请选择语言 / Please choose your language:
1. 中文
2. English

选择后会保存语言偏好，后续使用相应语言的核心菜单、AI 回复和明日建议报告。 语言选择完成前，“1/2”表示语言；完成后才按功能菜单编号操作。 随时说“切换为英文 / Switch to English”，或执行 garmin-assistant language en。 切回中文用 garmin-assistant language zh。核心编号和用户扩展不会改变。 MCP 无法自行向聊天窗口推送消息；客户端按连接指令在首次交互中展示欢迎语。

快速安装

需要 Python 3.12+ 和 Git。在 PowerShell 中：

git clone https://github.com/1838337544m-droid/garmin-assistant-api.git
cd garmin-assistant-api
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\garmin-assistant.exe init --timezone Asia/Shanghai

接下来单独运行：

.\.venv\Scripts\garmin-assistant.exe auth

看到 Garmin Personal API key (hidden): 后，在 PowerShell 窗口 按 Ctrl+V 粘贴你自己的整串个人密钥，再按 回车。 输入不会显示字符或星号，这是正常现象；只粘贴一次。 首次运行会接着显示双语欢迎语；输入 1 选中文或 2 选 English，再按回车。 看到 "saved": true 只是保存成功，再单独运行连接检查：

.\.venv\Scripts\garmin-assistant.exe doctor --live

检查结果中 "garmin_status": "ok" 表示已成功读取 Garmin。不要把密钥 粘贴到 AI 聊天中，也不要把 auth 和检查命令一起粘贴。 不熟悉命令行请按零基础分步说明操作。

默认目标为 10 公里/60 分钟，可在 init 中用 --goal-km、--goal-minutes 修改。请配置自己的时区（默认 UTC）。 macOS/Linux 对应命令与说明见用户手册。

功能菜单

核心编号固定，可以隐藏，不能被自定义工作流覆盖。随时输入 显示原有功能菜单 恢复 1–7；自定义功能仍保留。 自定义工作流从 100 起编号，不自动执行第三方代码。

平台接入

通过 client-config 生成实际安装路径配置，见平台手册。 本版没有提供云端服务、浏览器插件或一键上架的官方应用。

数据和依据

• 初次同步默认 93 天，后续填补间隔并复查重叠日期；缺失及失败明确标识。

• 每次明日分析先同步；文献成功检索满 7 天再联网更新，也可手动立即更新。

• 结合个人 HRV、睡眠、静息心率及近期跑步负荷；不知道的症状不当作没有。

• 引用经典适能—疲劳、强度分配、Daniels 分类及近期适用研究。

• 新论文标为待评估；不会因出现新文章就自动改写训练规则。

• 明日结果是预建议，晨起应复评；不作医疗放行、伤病概率或最快达标保证。

配置、密钥、缓存、报告与自定义菜单均位于个人数据目录，更新源码不会 覆盖。工具结果会发送给所连接的 AI，请按自己的隐私偏好选择平台。

更新与扩展

维护者不定期发布版本；用户主动更新，不静默下载执行新代码。 固定编号、独立配置和数据目录用于保留用户偏好。 升级、回滚与发版步骤见维护手册。 MIT 开源许可允许修改和 fork；“核心不变”是官方发行版及扩展接口的 兼容约定，不是禁止别人修改源码。详见 贡献说明。

自检

python -m pip install -e ".[dev]"
python -m pytest -q
python scripts/check_release.py
python -m build

仓库 CI 在 Windows/macOS/Linux 运行合成测试，不使用真实 Garmin 密钥。 实际完成的测试范围和客户端限制见参考与自检。