garmin-mcp

一个本地 MCP 服务器，将你的 Garmin Connect 活动、健康和训练数据（活动、HRV、睡眠、心率、压力、Body Battery、训练准备状态、心率/功率区间、乳酸阈值、FTP、VO2max、个人纪录、训练课、已计划训练课和训练计划）以工具的形式提供给 Claude Desktop。

它通过 garminconnect 库直接与实时 Garmin Connect API 通信。数据是只读的——不会向 Garmin 写回任何内容。

身份验证工作原理

Garmin 登录有意在两个独立位置进行：

• scripts/setup_auth.py — 一个交互式脚本，由你自己在终端中运行。它使用你的邮箱/密码登录，如果 Garmin 要求，会提示你输入 MFA 代码，并将生成的会话令牌保存到 ~/.garmin_mcp/tokens。

• MCP 服务器（src/garmin_mcp/server.py）由 Claude Desktop 无头启动，只会加载并静默刷新缓存令牌。它从不提示输入 MFA——Claude Desktop 没有给它可提示的终端，在那里阻塞 stdin 会导致工具调用挂起。如果缓存的会话缺失或已过期，工具调用会失败并返回错误，提示你重新运行 setup_auth.py。

你的 Garmin 密码存储在 macOS 钥匙串中（条目/服务 garmin-mcp，可在 Keychain Access 中查看），绝不会写入文件。只有你的 Garmin 登录邮箱（非机密信息）会保存在 ~/.garmin_mcp/config.json 中。

设置

1. 安装依赖：

   cd garmin_mcp
   uv sync

2. 运行一次性的交互式登录：

   uv run python scripts/setup_auth.py

   输入你的 Garmin Connect 邮箱和密码（密码随后会存储在钥匙串中，供下次使用）。出现提示时输入 MFA 代码。成功后你会看到确认信息和令牌缓存路径。

3. 通过编辑 ~/Library/Application Support/Claude/claude_desktop_config.json 并向其中添加（与任何其他 mcpServers 条目并列）来向 Claude Desktop 注册服务器：

   {
     "mcpServers": {
       "garmin": {
         "command": "uv",
         "args": ["run", "--project", "/Users/felix.guiony/Code/Perso/garmin_mcp", "garmin-mcp"]
       }
     }
   }

4. 完全退出 Claude Desktop（Cmd+Q，而不仅仅是关闭窗口），然后重新打开。工具/锤子图标应列出 garmin 工具。

工具

所有日期参数均接受 YYYY-MM-DD 格式，且默认值为今天。

故障排除

工具调用返回 "Garmin session error" / "run setup_auth.py" 消息。 你缓存的刷新令牌已过期或被撤销（这种情况偶尔会发生，例如在修改密码或长时间不活动后）。重新运行：

uv run python scripts/setup_auth.py

请求受限。 Garmin Connect 偶尔会限制快速请求；底层库会自动重试瞬时故障，但如果你看到速率限制错误，请稍等片刻再试。

在 Claude Desktop 之外直接验证服务器：

uv run mcp dev src/garmin_mcp/server.py

打开 MCP Inspector，以便你手动调用每个工具并检查其输出/模式。

项目结构

garmin_mcp/
  pyproject.toml
  src/garmin_mcp/
    auth.py      # keychain + token-cache helpers
    server.py    # FastMCP server and tool definitions
  scripts/
    setup_auth.py  # interactive one-time/occasional login