Skip to main content
Glama

个人 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 down

docker 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 tools
connection_statusA
Read-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_workoutA
DestructiveIdempotent

Permanently delete a workout template after explicit confirmation.

Inputs: workout_id (required), confirm. Returns: object

get_activity_splitsA
Read-onlyIdempotent

Get compact lap and interval metrics for one completed Garmin activity.

Inputs: activity_id (required). Returns: object

get_activity_summaryA
Read-onlyIdempotent

Get compact summary metrics for one completed Garmin activity.

Inputs: activity_id (required). Returns: object

get_recovery_statusA
Read-onlyIdempotent

Get available sleep, HRV, Body Battery, readiness, and training status for a date.

Inputs: date (required). Returns: object

list_activitiesA
Read-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_workoutsB
Read-onlyIdempotent

List Garmin calendar entries for a year and month.

Inputs: year (required), month (required). Returns: object

list_workoutsA
Read-onlyIdempotent

List workout templates from the user's Garmin Connect library.

Inputs: limit. Returns: result

preview_workoutA
Read-onlyIdempotent

Validate and preview Garmin JSON without changing Garmin Connect.

Inputs: workout (required). Returns: object

unschedule_workoutA
DestructiveIdempotent

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

    A4/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Personal MCP server for interacting with your Garmin Connect data. Exposes 62 tools across 11 domains including activities, health, training, and workouts.
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Exposes personal Garmin Connect data to MCP-capable clients like Claude and Gemini. Enables querying daily stats, heart rate, sleep, activities, and managing workouts.
      16
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Provides read-only access to your Garmin Connect health data, including sleep, HRV, body battery, stress, training readiness, and activities, through an MCP server.
      14
      -