garmin-mcp

一个小型 MCP 服务器，让 Claude Desktop 对 Garmin Connect 中的跑步、力量训练和卡路里数据拥有只读访问权限。它包含三个工具，设置大约需要十五分钟。

我构建这个工具是为了跟踪进度（以及其他事项），并分析我自己训练中的一些数据（例如，我的轻松跑配速如何变化，或者我在跑步的日子里举了什么重量），而无需手动导出 CSV。它直接与 Garmin 的 Connect API 通信，因此中间没有第三方服务，也不会将任何数据上传到任何地方。

工具

• list_runs(limit, start)：日期、跑步类型、距离、时间、平均配速、平均和最大心率、步频、温度。也涵盖跑步机跑步。

• list_strength(limit, start)：日期、训练名称、时长、组数、次数、总卡路里和活动卡路里、平均和最大心率。

• daily_calories(days, end)：每日总计、活动卡路里和基础代谢卡路里，以及步数和静息心率。

start 是行偏移量，end 是日期，因此 Claude 可以翻页浏览多年的历史记录，而不仅仅是最近几条。

所有操作都是只读的。底层库（garth-ng）确实暴露了写入端点，但这里没有任何代码调用它们：这是确保安全的唯一方式，因为令牌本身授予了完整的账户访问权限。

要求

Python 3.12+、uv、Claude Desktop 以及一个 Garmin Connect 账户。以下命令假设使用 Unix shell，因此适用于 macOS 或 Linux；Windows 也可以，但路径不同。Claude Desktop 本身可在 macOS、Windows 和 Linux（测试版，适用于 Ubuntu 和 Debian）上运行。这在 Claude 移动应用或 claude.ai 中无法使用，因为本地 stdio 服务器没有可供它们连接的 URL。

设置

1. 将你的 Garmin 密码更改为你在其他地方未使用过的密码，因为你即将在脚本中输入它。

2. 克隆并安装：

git clone https://github.com/SuvirRathore/garmin-mcp-public.git
cd garmin-mcp-public
uv sync

3. 进行一次身份验证。这将用你的密码交换保存在 ~/.garth 中的 OAuth 令牌，之后就不再需要密码了：

cd garmin-mcp-public
uv run auth_setup.py

如果提示，请输入你的 MFA 代码。OAuth1 令牌有效期约为一年，OAuth2 令牌会自动刷新，因此这大致是每年一次的任务。将 ~/.garth 视为凭证：任何持有它的人都可以读取你的整个 Garmin 账户。

4. 在引入 Claude 之前，直接测试工具。如果失败，那是身份验证或端点问题，而不是 MCP 问题，并且在此级别调试比通过 Desktop 的日志快得多：

cd garmin-mcp-public
uv run python -c "import server; print(server.list_runs(3))"
uv run python -c "import server; print(server.list_strength(3))"
uv run python -c "import server; print(server.daily_calories(7))"

5. 找到配置所需的两个绝对路径：

cd garmin-mcp-public
which uv
pwd

6. 创建或编辑 Claude Desktop 的配置文件，并粘贴下面的代码块，将两个路径替换为步骤 5 的输出。粘贴你的真实路径也会移除两个 YOUR_USERNAME 实例。该文件位于 macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json 和 Windows 上的 %APPDATA%\Claude\claude_desktop_config.json；在 Linux 测试版上，请查看 Anthropic 的 Claude Desktop 文档以获取当前位置。

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uv",
      "args": ["--directory", "/Users/YOUR_USERNAME/path/to/garmin-mcp-public",
               "run", "server.py"]
    }
  }
}

两个路径都必须是绝对路径。Desktop 使用最小的 PATH 启动服务器，因此即使在你的 shell 中有效，裸的 uv 也会失败。如果你已经配置了其他服务器，请将 garmin 条目添加到它们旁边，而不是替换整个对象。如果你在 TextEdit 中编辑此文件，请先关闭智能引号：花括号引号是无效的 JSON。

7. 完全退出 Claude Desktop（Cmd-Q，不仅仅是关闭窗口）并重新打开。配置文件仅在启动时读取。然后询问它类似“显示我最近五次跑步和本周的卡路里消耗”之类的问题，并批准工具调用。

如果不起作用

首先验证 JSON，然后读取服务器的 stderr。以下是 macOS 的路径；请根据你的平台进行调整：

cd garmin-mcp-public
uv run python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
tail -50 ~/Library/Logs/Claude/mcp-server-garmin.log

每次调用都出错通常意味着令牌已过期：重新运行 auth_setup.py。Claude 内部的“添加自定义连接器”对话框与此无关，因为它期望一个远程 HTTPS URL。

给扩展此工具的人的说明

Garmin 的 Connect API 没有文档，其字段名称会发生变化，因此当某些内容返回为空时，请检查一个真实对象，而不是猜测。将其保存为仓库中的 probe.py 并使用 uv run probe.py 运行，而不是粘贴到 shell 中：

import garth

garth.resume("~/.garth")
a = garth.connectapi(
    "/activitylist-service/activities/search/activities",
    params={"start": 0, "limit": 1},
)[0]
print(sorted(a))

在添加工具之前，有两个行为值得了解。activityType 过滤器仅接受父类别：running 有效并静默包含 treadmill_running，而 strength_training 返回 HTTP 400，必须作为 fitness_equipment 请求，然后在 Python 中过滤。此外，每个活动携带大约一百个字段，因此将它们映射到你需要的少数几个：返回原始的 Garmin JSON 会在每次调用时淹没上下文窗口。

出于同样的原因，保持工具数量少。三个具有描述性文档字符串的专注工具比十几个模糊的工具更好，因为 Claude 在选择调用哪个工具时会读取文档字符串。

MIT 许可。