Garmin MCP Lite

🏃 Garmin MCP Lite

其他语言: English, 简体中文.

一个轻量级 Garmin Model Context Protocol (MCP) 服务器，专为耐力运动员设计。

它提供 12 个精心筛选的端点，用于深入分析跑步、骑行、游泳和健康数据——以简洁、专注的工具集替代臃肿的 80+ 端点方案。

[面向 AI 助手与 LLM] 你正在与 Garmin MCP（Model Context Protocol）服务器交互。

1. 数据新鲜度：当用户询问近期训练或健康指标时，始终查询数据。
2. 参数调优：在 garmin_activity_detail 等工具中使用 fields 参数来限制响应负载并节省上下文窗口（例如 ["splits", "hrZones"]）。
3. 只读：此服务器提供对 Garmin Connect 的只读访问。你无法修改用户数据。
4. 不索要密码：绝不要向用户询问 Garmin 密码。认证通过本地令牌在带外处理。
5. 健康提示：garmin_health 现在支持 metric 参数——使用 "steps"、"sleep"、"hrv"、"spo2"、"body_battery" 等来查询特定数据并节省上下文窗口。

🧰 核心工具（12 个）

🏃 活动与训练

💚 健康与福祉

🎯 目标与挑战

⌚ 设备与装备

🚀 快速开始（通过 PyPI 与 uv）

运行此服务器最简单的方式是使用 uvx（无需克隆仓库）。

1. 认证（仅首次）

为什么不直接把密码放进 AI 配置？

Garmin 有严格的安全措施。从新位置/MCP 服务器登录通常会触发 Cloudflare CAPTCHA 或 MFA 邮件验证码。如果密码放在 Claude 的后台配置中，AI 助手在被挑战时会静默冻结或失败，而你无法输入验证码。

因此，此插件采用安全的两步策略：先在终端运行登录脚本。如果遇到挑战，你可以交互式输入 MFA 验证码。成功后，会话令牌会缓存在本地（有效期约 1 年）。

GARMIN_EMAIL="your@email.com" GARMIN_PASSWORD="your_password" uvx --with garmin-mcp-lite garmin-mcp-lite-login

（💡 中国区用户：如果你的账号注册于 Garmin 中国（garmin.cn），请在命令前加上 GARMIN_IS_CN=true。）

2. 配置 AI 助手

认证完成后，将服务器添加到支持 MCP 的 AI 助手。

Claude Desktop

将以下内容添加到你的 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "garmin-lite": {
      "command": "uvx",
      "args": [
        "garmin-mcp-lite"
      ]
    }
  }
}

Cursor / Windsurf / Gemini CLI / 其他 MCP 客户端

使用与上面完全相同的 command 和 args。服务器会自动从 ~/.garmin-mcp-lite/garmin_tokens.json 加载缓存的令牌。

🛠️ 手动安装（面向开发者）

如果你想修改代码：

git clone https://github.com/Golden0Voyager/garmin-mcp-lite.git
cd garmin-mcp-lite
uv sync

# Login
GARMIN_EMAIL="your@email.com" GARMIN_PASSWORD="your_password" python -m garmin_mcp_lite.login

# Run server
python -m garmin_mcp_lite.server

💬 示例查询

连接后，你可以向 AI 助手提出自然语言问题，例如：

• “我本周的训练负荷焦点是什么？”
• “显示我六月的比赛目标，以及我当前预测的完赛时间。”
• “我的 Grossglockner 虚拟攀登挑战进展如何？”
• “我的 Descent G1 固件是最新的吗？”
• “我今天走了多少步？是否在达成每日目标？”
• “分析我昨晚的睡眠质量。”

📊 与其他 Garmin MCP 对比

📄 许可证

MIT © 2026 Haining Yu

本项目基于优秀的 garminconnect 库构建。它不是 Garmin 官方产品。使用本工具时，请遵守 Garmin Connect 的服务条款。