Garmin Assistant API
Integrates with the Garmin Personal API to sync and analyze personal exercise and health data, including activities, sleep, heart rate, HRV, steps, stress, and Body Battery, and to provide training and recovery recommendations.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Garmin Assistant (API edition) | Garmin 助手(API)版本
English version
Start here — no coding needed
Install with AI · Download Windows installer · Step-by-step setup
With a local AI agent, copy the installation prompt. Otherwise download the release's Windows-Installer.zip, extract all files and double-click Install.cmd. The local setup window lets you choose English/中文, enter your key privately and select a client. For DeepSeek Flash or V4 Pro, choose DeepSeek API in setup and open Garmin Assistant DeepSeek. DeepSeek setup Internet is required. Ordinary web chats cannot install local software by receiving a prompt.
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.git garmin-assistant-api
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_YorkSet your own IANA timezone rather than copying the example blindly. Default is UTC.
In setup, choose swimming, cycling or running, then enter your target distance and time. From the
CLI, use init --sport swimming --goal-km 1.5 --goal-minutes 30 to save a 1,500 m swim goal.
For complete Windows and macOS/Linux instructions, see the beginner user guide.
Run authentication separately:
.\.venv\Scripts\garmin-assistant.exe authAt 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
ID | Core function |
1 | Sync data and fill the interval since the previous successful sync |
2 | Review 30-day training frequency and performance trends, plus 90-day HRV, resting heart rate, sleep and SpO₂ |
3 | Review fatigue and recovery using personal trends, reported fatigue and soreness, and recent training volume |
4 | Plan tomorrow's swimming, cycling or running around your selected target distance and time |
Say Show original function menu or 显示原有功能菜单 to display the previous seven commands. Custom prompt workflows retain IDs starting at 100. They cannot override core tools and do not execute arbitrary third-party code.
AI client compatibility
Client | Connection offered by this edition |
Claude Desktop / Claude Code | Local stdio MCP configuration |
GPT / Codex environments with local execution | Register the generated absolute command as a local MCP |
Ordinary ChatGPT web/mobile | Generate a report locally and upload it; no remote OAuth connector is provided |
Doubao editions that expose local MCP | Configure stdio through that edition's supported entry point |
Ordinary Doubao chat / clients without local MCP | Upload a locally generated report; no automatic local sync |
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 buildCI runs synthetic tests on Windows, macOS and Linux without personal Garmin credentials. See verification scope and self-check records.
Related MCP server: garmin-mcp
中文版本
从这里开始:不需要懂代码
交给 AI 安装 · 下载 Windows 安装包 · 一步步安装说明
如果 AI 能操作你的电脑,复制安装指令即可;否则在发布页下载 Windows-Installer.zip, 完整解压后双击 Install.cmd。本地窗口会让你选择中文/English、私密输入密钥并选择客户端。 使用 DeepSeek Flash 或 V4 Pro 时,在设置中选 DeepSeek API,然后打开 Garmin Assistant DeepSeek。DeepSeek 接入说明 安装需要联网;普通网页聊天不能只凭收到一段指令就在电脑上安装软件。
用自己的 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.git garmin-assistant-api
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 和检查命令一起粘贴。
不熟悉命令行请按零基础分步说明操作。
初始设置先选游泳、自行车或跑步,再填写距离和时间。命令行可用
init --sport swimming --goal-km 1.5 --goal-minutes 30 保存 1500 米游泳目标。
请配置自己的时区(默认 UTC)。
macOS/Linux 对应命令与说明见用户手册。
功能菜单
编号 | 核心功能 |
1 | 同步数据、补齐询问间隔 |
2 | 截至目前训练效果与状态。近 30 天运动频次和主要数据,近 90 天 HRV、静息心率、睡眠和血氧 |
3 | 疲劳与恢复。结合个人趋势、主观疲劳和酸痛、近期训练量,附研究出处 |
4 | 明天运动建议。选择游泳、自行车或跑步,再填写目标距离与时间 |
输入 显示原有功能菜单 可调出原来的七项功能。自定义功能仍保留。 自定义工作流从 100 起编号,不自动执行第三方代码。
平台接入
平台 | 本版接入方式 |
Claude Desktop / Claude Code | 本地 stdio MCP 配置;桌面版也可按客户端支持的扩展机制自行封装 |
GPT / Codex,支持本地 MCP 的桌面环境 | 用生成的绝对命令添加本地 MCP |
普通 ChatGPT 网页/手机聊天 | 本地生成报告后上传;本版不提供远程 OAuth 连接器 |
豆包工作等具有本地 MCP 入口的版本 | 按该版本入口配置 stdio;不能推断所有豆包版本都支持 |
普通豆包聊天 / 无本地 MCP 的客户端 | 生成报告后上传分析,不能自动同步本机 |
通过 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 密钥。 实际完成的测试范围和客户端限制见参考与自检。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Garmin Connect MCP server for ChatGPT, Claude and any AI agent: list activities, download FIT file, read sleep and HRV, get training status, create workout and schedule workout in your own Garmin Connect account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Garmin Connect yourself; Cotlet does not store your password and you need no Garmin Connect API key. About the official Garmin Connect API: Yes, in part (checked 27 Oct 2026). Garmin reopened its Connect Developer Program on 21 Oct 2026. Setup and FAQ: https://cotlet.dev/integrations/garmin-api-mcp-server
Adaptive running coach MCP server — training data, plans, and recovery for AI assistants.
AI coach for Garmin: builds training plans and structured workouts, synced straight to your watch.
Related MCP Servers
- AlicenseBqualityBmaintenanceDownloads all your Garmin health and fitness data into a local SQLite database and exposes 45 MCP tools for AI analysis, enabling assistants to query sleep, training load, HRV, and more.4885 PyPI173AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceA local MCP server that exposes your Garmin Connect data—sleep, HRV, training readiness, workouts, and more—to any MCP-compatible AI assistant. Runs entirely on your machine and keeps your Garmin credentials private.MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude and any MCP client to read a user's own Garmin account in plain language, covering activities, time-series charts, thresholds, sleep, HRV, Body Battery, stress, readiness and trends. It also serves a private local dashboard that downloads the full training and health history, correlates metrics across views, and exports any table as CSV.MIT
- AlicenseNot gradedqualityBmaintenanceSyncs your own Garmin Personal API data into a local SQLite archive and lets any MCP-capable AI assistant query sleep, HRV, stress, body battery, training and activity trends through natural language, with optional interactive charts. Everything runs locally with your own API key, so private health data stays on your machine.76 PyPI1Apache 2.0