AI导哈

健身数据分析服务

Garmin Workouts MCP Server 是一个连接 Garmin Connect API 的服务，通过 MCP 标准将用户的健身和健康数据暴露给 AI 代理，支持查询活动数据、获取洞察和生成 AI 训练计划。

  • by brunosantos
  • Python
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 brunosantos/garmin-workouts-mcp

使用说明

Garmin健身MCP服务器

Garmin锻炼模型上下文协议（MCP）服务器连接到Garmin Connect API，并将您的健身和健康数据暴露给支持MCP标准的AI代理。用户可以使用此服务器从Claude Desktop或VS Code Copilot等人工智能客户端访问您的Garmin活动、锻炼和锻炼模板，使用户能够查询他们的活动数据，获得见解并获得人工智能生成的锻炼计划。

此项目处于早期开发阶段（v0.1），目前支持对活动、锻炼和锻炼模板的只读访问。

源代码是原始Garmin MCP服务器的简化和重构版本，可在 garmin_mcp.最初的mcp解决方案仍然可用并得到维护，但该分叉版本旨在减少人工智能代理的数据访问表面积，并专注于创建训练计划的核心功能，而不是暴露Garmin Connect API的所有数据和功能。

Garmin的API可通过 python garminconnect 图书馆和garth

特性

  • 列出支持分页的最近活动
  • 获取详细的活动信息
  • 访问锻炼和训练计划
  • 浏览锻炼模板

用法示例

一旦连接到Claude Desktop/VS Code Copilot，您可以提出以下问题：

基本查询：

  • “显示我最近跑步的详细信息”
  • “根据我最近的活动制定下周的锻炼计划”
  • “我下一次计划锻炼是什么时候？”
  • “制定一个以对话速度轻松跑30分钟的锻炼计划”
  • “制定一个以5:15分钟/公里的速度跑5公里的锻炼计划”
  • “制定一个有间隔的锻炼计划：6×400米@4:10-4:20/km，90秒恢复（包括15分钟的热身/冷却）”

AI Coach辅助查询：

  • “我可以使用哪些锻炼模板来提高我的5公里时间？”
  • “根据我最近的活动，本周我应该做什么锻炼来为半程马拉松做准备？”
  • “根据我最近的活动，为下一次哈克尼半程马拉松制定一个锻炼计划，目标是在1小时45分内跑完。”
  • “上传一个结构化的45分钟阈值跑步训练，并安排在下周二进行”
  • “看看我最近4周的跑步，告诉我是训练过度还是准备增加里程”
  • “上周日跑步时，我在每个心率区花了多少时间？”
  • “比较我最近5次跑步的速度和心率——我是否变得更健康了？”
  • “我6周后有一场比赛——为我制定一个渐进的每周锻炼计划，并将每节课添加到我的日历中”

工具覆盖范围

此MCP服务器为以下域实现了工具：

  • ✅ 活动管理 --13个只读工具🏃

    • 📋 get_activities --列出支持分页的活动（最新活动优先）
    • 📅 get_activities_by_date --列出两个日期之间的活动，可选择按类型筛选
    • 📅 get_activities_fordate --列出在特定日期记录的活动
    • 🔍 get_activity --获取单个活动的详细信息
    • 📊 get_activity_splits --获取活动的圈数/分割数据
    • 📊 get_activity_typed_splits --为活动键入分割（跑步/步行等）
    • 📊 get_activity_split_summaries --获取活动的拆分摘要统计信息
    • 🌤️ get_activity_weather --记录活动期间的天气状况
    • ❤️ get_activity_hr_in_timezones --获取某项活动在HR区域的心率分布
    • 👟 get_activity_gear --获得用于活动的装备（鞋子、自行车等）
    • 🏋️ get_activity_exercise_sets --为力量训练活动准备运动套装
    • 🏷️ get_activity_types --列出Garmin Connect支持的所有活动类型
    • 🔢 count_activities --获取帐户中的活动总数

  • ✅ 锻炼 --11个读/写工具💪

    • 📋 get_workouts --列出Garmin Connect训练库中的所有训练
    • 🔍 get_workout_by_id --通过数字ID或UUID获取锻炼的完整细节
    • ⬆️ upload_workout --从结构化JSON数据创建新的训练
    • ⬆️ upload_workouts --在一次调用中从结构化JSON数据创建多个训练
    • 🗑️ delete_workout --从库中永久删除训练
    • 🗑️ delete_workouts --在一次通话中从库中永久删除多个训练
    • 📅 schedule_workout --将锻炼安排在特定的日历日期
    • 📅 schedule_workouts --在一次通话中安排多项锻炼（或上传并在线安排）
    • 📅 get_scheduled_workouts --列出日历上两个日期之间安排的锻炼
    • 🗓️ get_training_plan_workouts --获取Garmin教练/训练计划中给定一周的训练
    • ⬇️ download_workout --下载FIT文件格式的训练

  • ✅ 锻炼模板 --5 MCP资源📂

    • 🏃 workout://templates/simple-run --基本预热/运行/冷却结构
    • ⚡ workout://templates/interval-running --重复组间歇训练（6×400m）
    • 🎯 workout://templates/tempo-run --以心率区为目标的速度跑
    • 🏋️ workout://templates/strength-circuit --重复组力量训练回路
    • 📖 workout://reference/structure --用于构建训练的完整JSON结构参考

OAuth作用域注释

此服务器使用 garminconnect 和 加思 用于身份验证的库，它依赖于Garmin的SSO OAuth令牌。访问令牌授予对Garmin Connect API的读写权限。令牌作用域在身份验证库中不可由用户配置(garth).出于这个原因，MCP工具级别的设计应用了最低权限访问，如下所示：

  • 活动管理 --列出和检索活动的只读操作。对活动（例如创建、更新或删除活动）不执行写入操作。无法访问用户资料或其他敏感数据，如GPS坐标。
  • 锻炼 --所需的读写操作（列出、上传、安排、删除锻炼）

设置

安全注意事项

[！注意] Garmin的官方API程序 仅供企业使用，个人开发人员无法访问。我试图访问官方的API，但被拒绝了，因为我是作为一个开源个人项目来做这件事的。因此，我转向其他现有的开源库。这 garminconnect 库使用反向工程的API端点，并依赖于通过Garmin Connect web/移动登录流获得的OAuth令牌。这 garmin-mcp-auth 该工具是获取这些令牌以供MCP服务器使用的一种变通方法，但它不是官方或长期的解决方案。

Garmin锻炼MCP取决于 Garmin连接库 并且使用 Garth图书馆 用于身份验证，这依赖于长期使用的OAuth令牌。 Garth库使用Garmin Connect的mobile-app SSO流来获取和持久化长期（一年）会话令牌，然后python-arminconnect（API Wrapper）使用这些令牌来调用Garmin Connect API端点。 这 garmin-mcp-auth 该工具是一个一次性设置实用程序，提示您输入Garmin Connect凭据和MFA代码（如果启用）以获取这些令牌。然后将令牌保存在本地，并由MCP服务器在向Garmin Connect发出API请求时用于身份验证。

此解决方案中的秘密管理可能被认为是不安全的，特别是使用长期使用的OAuth访问令牌。我们正在研究替代方案，例如具有自动刷新或与外部秘密管理器或密钥库集成的短期令牌。与此同时，您必须进行预身份验证，以获得服务器运行所需的令牌。请自行决定使用此工具，并注意在计算机上存储凭据和令牌的安全影响。然而，MCP工具的范围仅限于活动的只读访问和锻炼的读写访问，从而最大限度地降低了潜在风险。

先决条件

  • Python 3.12+
  • Garmin Connect帐户
  • 如果您的帐户启用了MFA，则可能需要MFA

步骤1：预认证（一次）

在添加到Claude Desktop或VS Code Copilot之前，请在终端中进行一次身份验证：


# Install and run authentication tool
uvx --python 3.12 --from git+https://github.com/brunosantos/garmin-workouts-mcp garmin-mcp-auth

# You'll be prompted for:
# - Email (or set GARMIN_EMAIL env var)
# - Password (or set GARMIN_PASSWORD env var)
# - MFA code (if enabled on your account)

# OAuth tokens will be saved to ~/.garminconnect

您可以随时通过以下方式验证您的凭据

uv run garmin-mcp-auth --verify

注： 这将在以下位置创建一个本地文件 ~/.garminconnect 使用您的Garmin Connect长期代币（一年）。MCP服务器将读取此文件以验证API请求。这些代币的有效期为一年。

[！警告]
这里有龙🐉. 长寿命令牌是一种安全风险，违背了OAuth的最佳实践，但它是底层的一种限制 garminconnect 图书馆。请谨慎使用，并注意安全影响。 出于这个原因，我将MCP服务器的范围限制为仅必要的API端点（活动和锻炼模板为只读，锻炼为读写），以最大限度地减少潜在风险。 我正在研究一种使用具有自动刷新功能的短期代币的替代方案。

使用Claude Desktop

步骤2：配置Claude桌面

先决条件： 完成 步骤1：预认证 在配置Claude Desktop之前。

添加到您的Claude Desktop MCP设置 没有 资格证书：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "garmin-workouts": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "git+https://github.com/brunosantos/garmin-workouts-mcp",
        "garmin-workouts-mcp"
      ]
    }
  }
}

重要提示： 不 GARMIN_EMAIL 或 GARMIN_PASSWORD 配置中需要！服务器使用您保存的令牌。

步骤3：重新启动克劳德桌面

您的Garmin数据现在可以在Claude Desktop中使用！

使用VS代码

先决条件： 完成 步骤1：预认证 在配置VS代码之前。

为了快速安装，请使用下面的一键安装按钮之一：

对于手动安装，您可以使用以下方法之一配置MCP服务器：

方法1：用户配置（推荐） 将配置添加到用户级MCP配置文件中。打开命令选项板(Ctrl + Shift + P)然后跑 MCP: Open User Configuration。这将打开您的用户 mcp.json 您可以在其中添加服务器配置的文件。

方法2：工作空间配置 或者，您可以将配置添加到名为的文件中 .vscode/mcp.json 在您的工作空间中。这将允许您与他人共享配置。

有关VS Code中MCP配置的更多详细信息，请参阅 官方VS Code MCP文档.

{
  "servers": {
    "garmin-workouts": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "git+https://github.com/brunosantos/garmin-workouts-mcp",
        "garmin-workouts-mcp"
      ]
    }
  }
}

重要提示： 不 GARMIN_EMAIL 或 GARMIN_PASSWORD 配置中需要！服务器使用您在预身份验证步骤中保存的令牌。

开发设置

直接从存储库的本地副本：

  1. 添加此服务器配置：
{
  "mcpServers": {
    "garmin-workouts-local": {
      "command": "uv",
      "args": [
        "--directory",
        "<full path to your local repository>/garmin-workouts-mcp",
        "run",
        "garmin-workouts-mcp"
      ]
    }
  }
}

运行服务器

使用MCP Inspector在本地测试服务器

Inspector直接通过npx运行，无需安装。从项目根目录运行：

npx @modelcontextprotocol/inspector uv run garmin--workouts-mcp

您将能够检查和测试这些工具。

登录问题

如果您遇到登录问题：

  1. 验证您的凭据是否正确
  2. 检查Garmin Connect是否需要额外验证
  3. 确保garminconnect包是最新的

测试

该项目包括对所有MCP工具的全面测试。 目前所有测试均通过（100%）.

运行测试

# Run all integration tests (default - uses mocked Garmin API)
uv run pytest tests/integration/

# Run tests with verbose output
uv run pytest tests/integration/ -v

# Run a specific test module
uv run pytest tests/integration/test_activity_management_tools.py -v

# Run end-to-end tests (requires real Garmin credentials)
uv run pytest tests/e2e/ -m e2e -v

测试结构

  • 集成测试 （49次测试）：使用FastMCP集成和模拟Garmin API响应测试所有MCP工具
  • 端到端测试 （9项测试）：使用真实的MCP服务器和Garmin API进行测试（需要有效的证书）

相关 MCP