Garmin MCP Server

一个 MCP 服务器，将你的 Garmin Connect 健康与跑步数据作为工具暴露出来——这样像 DeepSeek 这样的 LLM 就可以每天分析你的手表数据，像一位根据你的真实数据调整的跑步/健康教练一样指导你。

Garmin watch ──sync──▶ Garmin Connect ──▶ garmin-mcp (this server)
                                                │  MCP tools (stdio / HTTP)
                                                ▼
                       DeepSeek (via scripts/deepseek_chat.py) or any MCP client
                       (Claude Desktop, Cherry Studio, Cursor, Claude Code, ...)

功能特性

• 每日健康摘要 —— 一次调用即可获取睡眠（时长/评分/阶段）、静息心率、HRV（昨夜 + 近一周）、身体电量、压力、SpO2、呼吸、步数、卡路里、高强度活动分钟数、晨间训练准备度以及当天任何训练。

• 跑步教练数据 —— get_run_analysis 聚合时段内的跑量、加权配速、心率、步频、海拔、训练负荷和每周趋势；get_activity_detail 深入查看每圈分段数据。

• 18 个工具 —— 覆盖每日指标、序列数据、活动、训练状态/准备度、最大摄氧量、比赛预测、乳酸阈值、心率区间、身体成分、个人纪录和个人资料。

• 基于令牌的认证 —— 只需登录一次（支持 MFA），会话会自动保存到磁盘；服务器自动恢复，无需再输入密码。

• 模拟模式 —— 设置 GARMIN_MOCK=true 即可返回确定性的合成数据，让你在接入真实账号之前测试整个流程。

• 内置 DeepSeek 桥接 —— scripts/deepseek_chat.py 直接为 DeepSeek 提供工具（函数调用），支持交互式模式或一次性 cron 模式。

Related MCP server: Garmin Workouts MCP Server

环境要求

• Python 3.10+（在 3.13 上开发）

• 一个 Garmin Connect 账号（免费），支持已启用双重认证的账号。

安装

cd /Users/jai/Documents/garmin_mcp_app

# 1. Create the virtualenv and install dependencies
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# 2. Configure credentials
cp .env.example .env        # then edit .env: GARMIN_EMAIL, GARMIN_PASSWORD

登录一次（交互式，支持 MFA）

.venv/bin/python -m garmin_mcp.login_cli --verify

该脚本会与 Garmin Connect 完成认证，如果你的账号启用了双重认证，它会提示你输入一次性 MFA 验证码；OAuth 令牌会保存到 ~/.garminconnect（仅属主可读写），并自动拉取少量真实数据点来确认一切正常。从此之后，服务器无需再输入密码。

登录故障排查：Garmin 偶尔会触发机器人/验证码挑战。解决办法：先在浏览器中登录一次 connect.garmin.com，然后重试登录脚本。如果被频率限制（429），请等待几分钟后再试。

不用真实账号测试（模拟模式）

GARMIN_MOCK=true .venv/bin/python scripts/smoke_test.py

该命令会通过 stdio 启动服务器，并像真实的 MCP 客户端那样运行所有工具——共 19 项检查，使用合成数据时全部预期通过。

接入 MCP 客户端

将你的客户端指向启动脚本 ./garmin-mcp-server（它会自动解析 venv 和 PYTHONPATH）：

Claude Desktop —— 添加到 claude_desktop_config.json（或使用 config/claude_desktop_config.example.json 中的示例）：

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/jai/Documents/garmin_mcp_app/garmin-mcp-server",
      "type": "stdio"
    }
  }
}

Cherry Studio（支持 DeepSeek 的桌面聊天工具）：进入 Settings → MCP Servers → Add，将 Name 设为 garmin，Type 设为 stdio，Command 设为 /Users/jai/Documents/garmin_mcp_app/garmin-mcp-server，然后把你的 DeepSeek 服务商选为模型。凭证来自项目文件 .env，因此客户端中无需配置环境变量。

Claude Code / Cursor / Cline：mcp add garmin -- /Users/jai/Documents/garmin_mcp_app/garmin-mcp-server

MCP Inspector（调试）：运行 npx @modelcontextprotocol/inspector，并将它指向以上命令——或通过 HTTP 方式运行服务器：

./garmin-mcp-server --transport streamable-http --port 8000

直接连接 DeepSeek（可选桥接）

DeepSeek 的聊天 API 支持 OpenAI 风格的函数调用，因此这个代码仓库内置了一个小型桥接程序：它启动 Garmin 服务器、把工具交给 DeepSeek，由后者决定要查询什么：

.venv/bin/pip install -r requirements-deepseek.txt   # adds 'openai'
# add DEEPSEEK_API_KEY to .env (see .env.example)

# interactive coach chat (uses prompts/coach.md as the system prompt)
.venv/bin/python scripts/deepseek_chat.py

# one-shot — cron-friendly ("daily analysis" job)
.venv/bin/python scripts/deepseek_chat.py --once "How was my recovery today? What should today's run be?"

在 prompts/coach.md 中撰写你自己的教练人设，并通过 --system-prompt prompts/coach.md 传入（这也是默认值）。仓库中还附带了一个入门提示词。

注意：DeepSeek 网页/聊天应用本身不支持 MCP，因此上面的桥接是让 DeepSeek 使用本服务器的正确方式。任何支持 MCP 的客户端（Claude Desktop、Cherry Studio、Cursor、Claude Code）也可以配合你自己的 DeepSeek API key 使用。

Web 应用（仪表盘 + 聊天）

自带浏览器前端，无需 MCP 客户端：

.venv/bin/pip install -r requirements-web.txt    # fastapi + uvicorn
./garmin-web                                     # http://127.0.0.1:8080
./garmin-web --mock                              # try it with synthetic data
./garmin-web --port 9000                         # different port

它的内容包含：

• 今日卡片 —— 睡眠评分/时长、HRV、身体电量、静息心率、压力、步数/目标、身体准备状态。

• 图表（最近 7/14/28 天）—— 静息心率、HRV、睡眠时长、身体电量、步数、呼吸、每周压力、每周跑步距离。

• 最近跑步表格 —— 距离、配速、心率、步频、海拔、训练时长、负荷。

• 教练聊天面板 —— 用自然语言提问；DeepSeek 会使用 Garmin 实时数据回答（将 DEEPSEEK_API_KEY 放到 .env 中）。无需 API key，仪表盘也能正常使用。

Web 应用在其整个生命周期内与 Garmin 服务器保持一个 MCP 会话，因此它与所有其他客户端一样复用完全相同的工具和认证。图表使用 Chart.js CDN，所以浏览器需要联网。

可用工具

所有输出都是 JSON 字符串；成功时为 {"ok": true, ...}，失败时为 {"ok": false, "error": ...}。日期格式为 YYYY-MM-DD（本地时间）。

项目结构

src/garmin_mcp/
  server.py          MCP server (tools, transports, CLI)
  garmin_client.py   real Garmin Connect client (token resume, cache) + mock
  formatters.py      raw Garmin payloads → compact LLM-friendly JSON
  config.py          env / .env settings
  login_cli.py       one-time interactive login (MFA-capable)
  deepseek.py        shared DeepSeek ↔ MCP chat core (CLI + web app)
scripts/
  smoke_test.py      end-to-end MCP client test (mock by default)
  deepseek_chat.py   DeepSeek ↔ MCP bridge (interactive or --once)
  web_app.py         FastAPI backend for the web dashboard + chat
web/                 frontend (index.html, app.js, style.css)
garmin-mcp-server    executable launcher for MCP clients
garmin-web           executable launcher for the web app
config/              Claude Desktop config example
prompts/coach.md     your coach system prompt (edit me)

说明与注意事项

• 本项目通过 Garmin 的非官方（Web/设备）接口和社区库 garminconnect 获取数据。Garmin 可能随时更改这些接口；由于 fmt 类防御式编写，缺失字段会优雅降级。

• 令牌文件包含长期有效的 refresh token——请保持私密（~/.garminconnect，权限 0600）。

• 服务器会对响应结果缓存 GARMIN_CACHE_TTL 秒（默认 600），避免 LLM 提出重叠问题时对 Garmin 造成大量压力。

• 仪表盘图表通过 CDN 加载 Chart.js，因此浏览器需要联网才能显示图表（卡片和表格在离线时仍可使用）。

• 无 Garmin 不受管理，仅限个人使用。

许可协议

MIT