garmin-mcp
个人 Garmin MCP
一个本地 MCP 服务器,用于通过非官方 Garmin 端点在 Garmin Connect 中创建和安排结构化训练。
这是一个实验性的个人项目。Garmin 可能随时更改端点、限制请求速率或撤销会话。请勿在未添加单独身份验证的情况下将服务器暴露到互联网。
功能
验证已保存的 Garmin 会话;
预览 Garmin JSON 而不做任何更改;
创建训练,并可选择将其添加到日历;
列出训练库和日历;
读取已完成的活动、紧凑摘要和圈数/分段指标;
读取可用的睡眠、HRV、Body Battery、Training Readiness 和 Training Status;
删除训练并从日历中移除训练;
支持跑步、骑行、步行和徒步;
支持时间、距离和
lap button步骤;支持间隔重复;
支持配速、心率、功率和踏频目标;
每次更改都需要
confirm=true。
Related MCP server: Garmin Connect MCP
安装
Docker Compose — 推荐
本地使用需要支持 Compose 的 Docker。从仓库根目录构建镜像:
docker compose build构建过程使用 uv 严格从 uv.lock 安装 Python 依赖。
运行一次交互式登录。密码和 MFA 代码直接在容器中输入,不会被存储。OAuth 令牌保存在私有 garmin-mcp_garmin_tokens 命名卷中:
docker compose --profile login run --rm garmin-login启动 MCP 服务器:
docker compose up -d garmin-mcp
docker compose ps端点在 http://127.0.0.1:8000/mcp 可用。要使用不同的本地端口:
GARMIN_MCP_PORT=8765 docker compose up -d garmin-mcp查看日志或停止服务器:
docker compose logs -f garmin-mcp
docker compose downdocker compose down 保留 Garmin 令牌。运行 docker compose down -v 会删除卷及其令牌。
不使用 Docker 的本地安装
需要 Python 3.12+ 和 uv。
cd /path/to/garmin-mcp
uv sync --extra dev一次性登录
uv run garmin-mcp-login脚本在需要时交互式请求电子邮件地址、密码和 MFA 代码。密码不会被存储。OAuth 令牌以受限权限保存到 .garmin-tokens/garmin_tokens.json。该目录已包含在 .gitignore 中。
要将令牌存储到其他位置:
export GARMIN_TOKEN_DIR=/safe/private/path/garmin-tokens
uv run garmin-mcp-login通过 stdio 的本地 MCP
export GARMIN_TOKEN_DIR=/safe/private/path/garmin-tokens
uv run garmin-mcp示例 MCP 客户端配置:
{
"mcpServers": {
"garmin": {
"command": "/absolute/path/to/garmin-mcp/.venv/bin/garmin-mcp",
"env": {
"GARMIN_TOKEN_DIR": "/safe/private/path/garmin-tokens"
}
}
}
}用于 ChatGPT 的 Streamable HTTP
export GARMIN_MCP_TRANSPORT=streamable-http
export GARMIN_MCP_HOST=127.0.0.1
export GARMIN_MCP_PORT=8000
export GARMIN_TOKEN_DIR=/safe/private/path/garmin-tokens
uv run garmin-mcp端点:http://127.0.0.1:8000/mcp。
ChatGPT 必须能够通过 HTTPS 访问该端点。可以使用受保护的隧道进行个人测试。请勿将此 MVP 直接暴露到互联网:它有意不包含用于访问 MCP 服务器本身的单独 OAuth 资源服务器。
示例 preview_workout 参数
{
"workout": {
"name": "6 x 800",
"sport": "running",
"description": "Controlled intervals",
"blocks": [
{
"steps": [
{
"step_type": "warmup",
"duration_type": "time",
"duration_value": 900
}
]
},
{
"repeat": 6,
"steps": [
{
"step_type": "interval",
"duration_type": "distance",
"duration_value": 800,
"target_type": "pace_seconds_per_km",
"target_low": 250,
"target_high": 260
},
{
"step_type": "recovery",
"duration_type": "time",
"duration_value": 120
}
]
},
{
"steps": [
{
"step_type": "cooldown",
"duration_type": "time",
"duration_value": 600
}
]
}
]
}
}配速值以秒/公里为单位指定:250 = 4:10/km,260 = 4:20/km。服务器会将其转换为 Garmin Connect 使用的 m/s 值。
预览后,使用相同的对象、YYYY-MM-DD 格式的日期和 confirm=true 调用 create_workout。
只读训练上下文
服务器提供紧凑的只读工具,用于根据已完成的工作调整未来计划:
list_activities列出包含起止日期的范围内的活动,并带有可选的 Garmin 活动类型过滤器;get_activity_summary返回单个活动的规划指标;get_activity_splits返回紧凑的圈数和间隔指标;get_recovery_status汇总单个日期的可用睡眠、HRV、Body Battery、Training Readiness 和 Training Status。
活动响应有意省略 GPS 坐标和所有者详细信息。恢复指标因 Garmin 设备、账户和日期而异。缺失的来源返回为不可用,不会导致整个恢复请求失败。
检查
uv run --extra dev pytest
uv run --extra dev ruff check .单元测试不联系 Garmin,也不需要凭据。
重要限制
这不是官方的 Garmin Training API。
频繁登录可能会收到 HTTP 429 响应;请重用保存的令牌。
令牌提供对 Garmin Connect 的访问,必须像密码一样保护。
如果创建成功但调度失败,工具返回
created_not_scheduled和workout_id;创建的训练保留在库中。在常规使用之前,请在 Garmin Connect 和特定手表型号上测试一个简单的训练。
Available Tools
11 toolsconnection_statusARead-onlyIdempotent
Verify that saved Garmin tokens can authenticate.
Inputs: no named parameters. Returns: object
create_workoutA
Create a Garmin workout and optionally schedule it on YYYY-MM-DD.
Call with confirm=false for a non-mutating confirmation response. Set confirm=true only after the user explicitly approves the preview and date.
Inputs: workout (required), confirm, schedule_date. Returns: object
delete_workoutADestructiveIdempotent
Permanently delete a workout template after explicit confirmation.
Inputs: workout_id (required), confirm. Returns: object
get_activity_splitsARead-onlyIdempotent
Get compact lap and interval metrics for one completed Garmin activity.
Inputs: activity_id (required). Returns: object
get_activity_summaryARead-onlyIdempotent
Get compact summary metrics for one completed Garmin activity.
Inputs: activity_id (required). Returns: object
get_recovery_statusARead-onlyIdempotent
Get available sleep, HRV, Body Battery, readiness, and training status for a date.
Inputs: date (required). Returns: object
list_activitiesARead-onlyIdempotent
List completed Garmin activities in an inclusive YYYY-MM-DD date range.
Returns compact planning metrics and omits GPS coordinates and owner details.
activity_type is an optional Garmin type key such as running or cycling.
Inputs: start_date (required), limit, end_date, activity_type. Returns: object
list_scheduled_workoutsBRead-onlyIdempotent
List Garmin calendar entries for a year and month.
Inputs: year (required), month (required). Returns: object
list_workoutsARead-onlyIdempotent
List workout templates from the user's Garmin Connect library.
Inputs: limit. Returns: result
preview_workoutARead-onlyIdempotent
Validate and preview Garmin JSON without changing Garmin Connect.
Inputs: workout (required). Returns: object
unschedule_workoutADestructiveIdempotent
Remove a scheduled workout from the calendar without deleting its template.
Inputs: scheduled_workout_id (required), confirm. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
The tools are generally distinct: connection_status, preview_workout, list/workout types, get_activity_summary vs splits, recovery, and create/delete/unschedule. There is slight overlap between list_workouts and list_scheduled_workouts, but descriptions clarify that one is templates and the other is calendar entries. The naming also helps distinguish them.
All tools follow a consistent verb_noun pattern: connection_status, preview_workout, list_workouts, list_scheduled_workouts, list_activities, get_activity_summary, get_activity_splits, get_recovery_status, create_workout, delete_workout, unschedule_workout. The pattern is uniform and predictable.
With 11 tools, the server covers a reasonable scope for a Garmin integration: connection check, workout preview/CRUD, activity listing/retrieval, and recovery status. Each tool serves a distinct function, and the count is within the typical range for a domain-specific server.
The surface appears complete for common Garmin workflows: managing workouts (create, delete, unschedule), viewing activities (list, summary, splits), checking recovery, and verifying connection. It includes both list and get operations, plus scheduling. There is a minor gap for updating workouts, but that may be acceptable given the preview/confirm workflow. Overall, it covers the primary user needs.
Related MCP Connectors
Remote MCP server for training, nutrition, wellness, and performance data with OAuth 2.0.
List, fetch, create, edit (replace), delete and schedule structured workouts on Garmin Connect (runn
MCP server for Withings health data — sleep, activity, heart, and body metrics.
Fitness MCP for coaches and gyms: build workouts and read clients' training from live Superset data.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenancePersonal MCP server for interacting with your Garmin Connect data. Exposes 62 tools across 11 domains including activities, health, training, and workouts.1MIT
- AlicenseBqualityCmaintenanceExposes personal Garmin Connect data to MCP-capable clients like Claude and Gemini. Enables querying daily stats, heart rate, sleep, activities, and managing workouts.16MIT
- AlicenseAqualityDmaintenanceMCP server for reading and querying Garmin Connect data, including activities, strength history, recovery, trends, and optionally creating workouts.12MIT
- FlicenseAqualityDmaintenanceProvides read-only access to your Garmin Connect health data, including sleep, HRV, body battery, stress, training readiness, and activities, through an MCP server.14-