](https://mseep.ai/app/taxuspt-garmin-mcp)
Garmin MCP服务器
此模型上下文协议（MCP）服务器连接到Garmin Connect，并将您的健身和健康数据暴露给Claude和其他兼容MCP的客户端。
Garmin的API可通过 python garminconnect 图书馆。
特性
- 列出支持分页的最近活动
- 获取详细的活动信息
- 管理活动名称
- 访问健康指标（步数、心率、睡眠、压力、呼吸）
- 查看车身成分数据
- 跟踪培训状态和准备情况
- 访问循环FTP和乳酸阈值指标
- 管理装备和设备
- 访问锻炼和训练计划
- 检查详细的锻炼步骤结构，包括重复组和游泳速度目标
- 每周健康汇总（步数、压力、强度分钟）
- 高级循环分析：动力区、FIT文件分析、DI2电子换档智能
- 训练负荷趋势（CTL/ATL/TSB）、心率变异性趋势、最大摄氧量趋势、呼吸频率趋势
- 功率持续时间曲线、VAM爬升检测、心脏漂移（有氧解耦）、W/kg计算
工具覆盖范围
此MCP服务器实现 110+工具 覆盖约90% python garminconnect 库（v0.3.2）：
- ✅ 活动管理（15个工具）
- ✅ 健康与保健（31个工具）-包括自定义轻量级摘要工具
- ✅ 训练与表现（13个工具）-包括CTL/ATL/TSB、HRV、最大摄氧量和呼吸趋势
- ✅ 锻炼（8个工具）
- ✅ 设备（7个工具）
- ✅ 齿轮管理（5个工具）
- ✅ 重量追踪（5个工具）
- ✅ 挑战与徽章（10个工具）
- ✅ 营养（8种工具）-食物记录、膳食、定制食物和食物记录
- ✅ 女性健康（3个工具）
- ✅ 用户配置文件（3个工具）
- ✅ 高级锻炼构建器（4个工具）-无需编写JSON即可创建和安排锻炼
- ✅ 课程（3个工具）-列出/上传GPX作为课程/删除课程
- ✅ 活动分析（2个工具）-FIT文件解析，功率持续时间曲线；需要功率计和/或Di2
注： 活动分析工具需要兼容的功率计（例如Garmin Rally、Favero Assioma、PowerTap P1）和/或Shimano Di2/SRAM eTap电子换档。这 fitparse 依赖关系会自动安装。故意跳过终点
出于性能或复杂性考虑，某些端点未实现：
高数据量：
get_activity_details()-返回大型GPS轨迹和图表数据（50KB-500KB）。使用get_activity()取而代之的是摘要。
专业锻炼形式：
upload_running_workout(),upload_cycling_workout(),upload_swimming_workout()-运动专项训练上传。使用upload_workout()用于一般锻炼。
维护和破坏性操作：
delete_activity(),delete_blood_pressure()-破坏性行动需要仔细考虑。- 内部/身份验证方法：
login(),resume_login(),connectapi(),download()-由图书馆自动处理。
如果您需要这些端点中的任何一个，请 打开一个问题.
高级锻炼工具
这些构建工具允许LLM创建和安排锻炼，而无需编写原始的Garmin JSON。
create_walk_run_workout
创建具有可选心率区域目标的步行/跑步间隔训练。
{
"name": "W3 Mié 2:2",
"run_seconds": 120,
"walk_seconds": 120,
"repeats": 9,
"warmup_min": 10,
"cooldown_min": 8,
"hr_zone": "Z3"
}退货： {"status": "success", "workout_id": 1234567890, ...}
create_z2_walk_workout
创建稳定的Z2步行训练。
{
"name": "Z2 Walk 45m",
"duration_min": 45,
"hr_min": 110,
"hr_max": 130
}退货： {"status": "success", "workout_id": 1234567890, ...}
create_strength_workout
从一系列练习中创建力量训练。未知名称退回到保留原始名称的通用步骤。
{
"name": "Full Body A",
"exercises": [
{"name": "Sentadillas", "sets": 3, "reps": 12, "rest_seconds": 90},
{"name": "Flexiones", "sets": 3, "reps": 15, "rest_seconds": 60},
{"name": "Peso muerto", "sets": 3, "reps": 10, "rest_seconds": 90}
]
}退货： {"status": "success", "workout_id": 1234567890, ...}
schedule_week
在一次通话中安排多项锻炼。
{
"week": [
{"date": "2026-05-12", "workout_id": 1234567890},
{"date": "2026-05-14", "workout_id": 1234567891}
]
}退货： {"status": "complete", "scheduled": [...]}
全流程示例
create_walk_run_workout(name="W3 Mié 2:2", run_seconds=120, walk_seconds=120,
repeats=9, warmup_min=10, cooldown_min=8)
→ workout_id = 1560092011
schedule_workout(workout_id=1560092011, date="2026-05-06")
→ OK同步手表后，训练将显示在Forerunner 965日历上。
一键安装（克劳德桌面）
将此服务器添加到Claude Desktop的最简单方法是通过 .dxt 桌面扩展文件——无需JSON编辑。
下载并安装
- 下载最新
garmin-mcp.dxt从 发布页面. - 拖动
.dxt将文件导入Claude Desktop窗口， 或 双击它， 或 首选 设置→ 扩展→ 安装扩展 并选择文件。 - Claude Desktop将提示您进行可选配置（令牌路径、电子邮件、密码）。
首次身份验证
该扩展程序会自动安装并运行服务器，但您必须向Garmin进行一次身份验证，然后才能获取数据：
uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_mcp garmin-mcp-auth这将OAuth令牌保存到 ~/.garminconnect之后，服务器在配置中没有任何凭据的情况下工作。
注： 代币的有效期约为6个月。重新运行 garmin-mcp-auth 当它们到期时。构建 .dxt 你自己
bash scripts/build_dxt.sh # produces garmin-mcp.dxt in the repo root______________________________________________________________________
设置
Claude Desktop快速入门
将此MCP服务器与Claude Desktop一起使用的最简单方法是在将服务器添加到配置之前进行一次身份验证。
先决条件
- Python 3.12+
- Garmin Connect帐户
- 如果您的帐户启用了MFA，则可能需要MFA
步骤1：预认证（一次）
在添加到Claude Desktop之前，请在终端中进行一次身份验证：
# Install and run authentication tool
uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_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注： 您还可以通过环境变量设置凭据：
GARMIN_EMAIL=your@email.com GARMIN_PASSWORD=secret garmin-mcp-auth如果你没有启用MFA，你也可以跳过 garmin-mcp-auth 并通过 GARMIN_EMAIL 和 GARMIN_PASSWORD 作为env变量直接发送到Claude Desktop（或其他MCP客户端，如果支持的话），请参阅下面的示例。
步骤2：配置Claude桌面
添加到您的Claude Desktop MCP设置 没有 资格证书：
macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"garmin": {
"command": "uvx",
"args": [
"--python",
"3.12",
"--from",
"git+https://github.com/Taxuspt/garmin_mcp",
"garmin-mcp"
]
}
}
}重要提示： 不 GARMIN_EMAIL 或 GARMIN_PASSWORD 配置中需要！服务器使用您保存的令牌。
步骤3：重新启动克劳德桌面
您的Garmin数据现在可以在Claude中使用！
______________________________________________________________________
开发设置
- 在新环境中安装所需的软件包：
uv sync运行服务器
配置
您的Garmin Connect凭据是从环境变量中读取的：
GARMIN_EMAIL：您的Garmin Connect电子邮件地址GARMIN_EMAIL_FILE：包含您的Garmin Connect电子邮件地址的文件路径GARMIN_PASSWORD：您的Garmin Connect密码GARMIN_PASSWORD_FILE：包含Garmin Connect密码的文件路径GARMIN_IS_CN：设置为true使用Garmin Connect China（Garmin.cn）而不是国际版本（默认：false)
基于文件的秘密在某些环境中很有用，例如在Docker容器中。请注意，您不能同时设置这两个 GARMIN_EMAIL 和 GARMIN_EMAIL_FILE，同样，您不能同时设置这两个 GARMIN_PASSWORD 和 GARMIN_PASSWORD_FILE.
Garmin Connect中国（Garmin.cn）
如果您使用Garmin Connect China（Garmin.cn）而不是国际版，请设置 GARMIN_IS_CN 环境变量 true:
# Pre-authenticate with Garmin Connect China
GARMIN_IS_CN=true garmin-mcp-auth
# Or use the CLI flag
garmin-mcp-auth --is-cn对于Claude Desktop，添加 GARMIN_IS_CN 到 env 章节：
{
"mcpServers": {
"garmin": {
"command": "uvx",
"args": [
"--python",
"3.12",
"--from",
"git+https://github.com/Taxuspt/garmin_mcp",
"garmin-mcp"
],
"env": {
"GARMIN_IS_CN": "true"
}
}
}
}对于Docker，添加 GARMIN_IS_CN=true 致你的 .env 将其归档或取消注释 docker-compose.yml.
使用MCP Inspector在本地测试服务器
Inspector直接通过npx运行，无需安装。从项目根目录运行：
npx @modelcontextprotocol/inspector uv run garmin-mcp您将能够检查和测试这些工具。
使用克劳德桌面
- 在Claude Desktop中创建配置：
编辑您的Claude Desktop配置文件：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%\Claude\claude_desktop_config.json
您有两种选择可以在本地与Claude一起运行MCP。
直接从github，无需克隆repo：
- 添加此服务器配置：
{
"mcpServers": {
"garmin": {
"command": "uvx",
"args": [
"--python",
"3.12",
"--from",
"git+https://github.com/Taxuspt/garmin_mcp",
"garmin-mcp"
],
"env": {
"GARMIN_EMAIL": "YOUR_GARMIN_EMAIL",
"GARMIN_PASSWORD": "YOUR_GARMIN_PASSWORD"
}
}
}
}您可能需要将完整路径添加到 uvx 您可以通过以下方式检查完整路径 which uvx
- 重新启动克劳德桌面
直接从存储库的本地副本：
- 添加此服务器配置：
{
"mcpServers": {
"garmin-local": {
"command": "uv",
"args": [
"--directory",
"/garmin_mcp",
"run",
"garmin-mcp"
]
}
}
}- 重新启动克劳德桌面
使用Docker
Docker为运行MCP服务器提供了一个隔离和一致的环境。
Docker Compose快速入门（推荐）
- 创建一个
.env使用您的凭据文件：
echo "GARMIN_EMAIL=your_email@example.com" > .env
echo "GARMIN_PASSWORD=your_password" >> .env- 启动容器：
docker compose up -d- 查看日志以监视服务器：
docker compose logs -f garmin-mcp直接使用Docker
# Build the image
docker build -t garmin-mcp .
# Run the container
docker run -it \
-e GARMIN_EMAIL="your_email@example.com" \
-e GARMIN_PASSWORD="your_password" \
-v garmin-tokens:/root/.garminconnect \
garmin-mcp使用基于文件的秘密（更安全）
为了增强安全性，特别是在生产环境中，请使用基于文件的机密而不是环境变量：
- 创建secrets目录并添加您的凭据：
mkdir -p secrets
echo "your_email@example.com" > secrets/garmin_email.txt
echo "your_password" > secrets/garmin_password.txt
chmod 600 secrets/*.txt- 编辑 并取消对秘密部分的注释：
services:
garmin-mcp:
environment:
- GARMIN_EMAIL_FILE=/run/secrets/garmin_email
- GARMIN_PASSWORD_FILE=/run/secrets/garmin_password
secrets:
- garmin_email
- garmin_password
secrets:
garmin_email:
file: ./secrets/garmin_email.txt
garmin_password:
file: ./secrets/garmin_password.txt- 启动容器：
docker compose up -d使用Docker处理MFA
如果您的Garmin帐户启用了多因素身份验证（MFA）：
- 在交互模式下运行容器：
docker compose run --rm garmin-mcp- 出现提示时，输入您的MFA代码：
Garmin Connect MFA required. Please check your email/phone for the code.
Enter MFA code: 123456- OAuth令牌将保存到Docker卷(
garmin-tokens)，因此您不需要在后续运行中重新进行身份验证。
- MFA设置后，您可以正常运行容器：
docker compose up -dDocker卷管理
OAuth令牌存储在持久的Docker卷中，以避免重新身份验证：
# List volumes
docker volume ls
# Inspect the tokens volume
docker volume inspect garmin_mcp_garmin-tokens
# Remove the volume (will require re-authentication)
docker volume rm garmin_mcp_garmin-tokens通过Docker与Claude Desktop配合使用
要将Docker化的MCP服务器与Claude Desktop一起使用，您可以将其配置为与容器通信。但是，请注意，MCP服务器通常通过stdio进行通信，这最适合直接执行进程。对于基于Docker的部署，考虑使用标准 uvx 方法如 使用克劳德桌面 取而代之的是部分。
用法示例
在Claude中连接后，您可以提出以下问题：
- “显示我最近的活动”
- “我昨晚睡得怎么样？”
- “我昨天走了几步？”
- “显示我最近跑步的详细信息”
- “分析我上次骑行的动力区，并与我的训练区进行比较”
- “显示我过去6周的CTL、ATL和TSB趋势”
- “从昨天的骑行开始，我的功率持续时间曲线是什么？估计一下我的FTP。”
- “分析我上次自行车活动的FIT数据——我在爬坡时的转换质量如何？”
- “显示我过去两周的HRV趋势，并标记任何复苏问题”
- “我本赛季最好的20分钟力量是什么？我什么时候设定的？”
故障排除
“生成进程失败：没有这样的文件或目录”
如果克劳德桌面找不到 uvx，这是因为 uvx 不在Claude Desktop使用的PATH中。要解决此问题，请执行以下操作：
- 查找位置
uvx已安装：
which uvx- 在配置中使用完整路径。例如，如果
uvx在/Users/username/.cargo/bin/uvx:
{
"mcpServers": {
"garmin": {
"command": "/Users/username/.cargo/bin/uvx",
"args": [
"--python",
"3.12",
"--from",
"git+https://github.com/Taxuspt/garmin_mcp",
"garmin-mcp"
]
}
}
}登录问题
如果您遇到登录问题：
- 验证您的凭据是否正确
- 检查Garmin Connect是否需要额外验证
- 确保garminconnect包是最新的
日志
有关其他问题，请查看Claude Desktop日志：
- macOS：
~/Library/Logs/Claude/mcp-server-garmin.log - 窗户：
%APPDATA%\Claude\logs\mcp-server-garmin.log
Garmin Connect多因素身份验证（MFA）
使用MCP服务器了解MFA
MCP服务器作为后台进程运行，没有直接的终端访问。如果您的Garmin帐户启用了MFA，您必须使用预身份验证工具进行一次身份验证，然后服务器才能运行。
推荐：预认证工具
处理MFA最简单的方法是使用专用的身份验证工具：
garmin-mcp-auth这将OAuth令牌保存到 ~/.garminconnect 以备将来使用。在Claude Desktop或其他MCP客户端中运行时，服务器将自动使用这些令牌。
其他选项：
# Use environment variables for credentials
GARMIN_EMAIL=you@example.com GARMIN_PASSWORD=secret garmin-mcp-auth
# Verify existing tokens
garmin-mcp-auth --verify
# Force re-authentication (e.g., when tokens expire)
garmin-mcp-auth --force-reauth
# Use custom token location
garmin-mcp-auth --token-path ~/.garmin_tokens替代方案：手动首次运行
您还可以通过交互式运行服务器进行身份验证：
# Store credentials in files for security
echo "your_email@example.com" > ~/.garmin_email
echo "your_password" > ~/.garmin_password
chmod 600 ~/.garmin_email ~/.garmin_password
# Run server interactively to authenticate
GARMIN_EMAIL_FILE=~/.garmin_email GARMIN_PASSWORD_FILE=~/.garmin_password \
uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_mcp garmin-mcp
# Enter MFA code when prompted
# Tokens will be saved automatically
# Now add to Claude Desktop config without credentials初始身份验证后，配置Claude Desktop 没有 凭据（令牌已保存）：
{
"mcpServers": {
"garmin": {
"command": "uvx",
"args": [
"--python",
"3.12",
"--from",
"git+https://github.com/Taxuspt/garmin_mcp",
"garmin-mcp"
]
}
}
}使用Docker和MFA
如果使用Docker，请按照以下步骤操作 以上部分介绍了持久令牌存储的简化体验。
MFA故障排除
错误：“需要MFA身份验证，但没有可用的交互式终端”
解决方案：
- 打开终端
- 运行：
garmin-mcp-auth - 输入凭据和MFA代码
- 重新启动克劳德桌面
令牌已过期
OAuth令牌定期过期（大约每6个月一次）。重新验证：
garmin-mcp-auth --force-reauth验证令牌是否有效
garmin-mcp-auth --verify测试
该项目包括对所有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_health_wellness_tools.py -v
# Run end-to-end tests (requires real Garmin credentials)
uv run pytest tests/e2e/ -m e2e -v测试结构
- 集成测试 （200多项测试）：使用FastMCP集成和模拟Garmin API响应测试所有MCP工具
- 端到端测试 （4项测试）：使用真实的MCP服务器和Garmin API进行测试（需要有效的证书）
从本地路径重新安装
如果您在当地收银台或叉子上工作：
uv tool install --python 3.12 --force C:\Users\aresd\Desktop\programacion\garmin_mcp