使用说明

Garmin Connect MCP服务器

模型上下文协议（MCP）服务器，提供对Garmin Connect数据的全面访问，包括睡眠分析、健康指标、活动和训练量分析。非常适合构建基于人工智能的健身洞察、训练分析和健康跟踪应用程序。

概述

此MCP服务器将您的AI助手（Claude Desktop、Claude Code或任何兼容MCP的客户端）直接连接到您的Garmin Connect帐户，从而启用：

实时健康洞察：访问睡眠、心率、步数、压力和身体电池数据
培训分析：按周、月或自定义日期范围汇总培训量
活动分析：通过过滤和分页检索详细的活动数据
多指标总结：获取全面的日常健康概览

技术栈：TypeScript、Node.js 20+、MCP SDK、garmin连接库

特性

🌙 睡眠分析

详细的睡眠阶段（深睡、浅睡、快速眼动、清醒）
睡眠评分和质量指标
持续时间和时间分析
总结和详细模式

💪 健康指标

步骤：每日步数、目标和进度跟踪
心率：静息HR、最大HR、区域和时间序列数据
身体成分：体重追踪和身体成分
压力与恢复：压力水平和身体电池指标

🏃 活动跟踪

带有筛选功能的最近活动列表
详细的活动信息（分段、圈数、指标）
特定活动数据（距离、持续时间、速度、海拔高度）
对大型数据集的分页支持

📊 培训量分析

每周培训汇总（ISO周标准）
月度培训总结
自定义日期范围分析（最多365天）
活动类型过滤（跑步、骑自行车、游泳等）
趋势分析（每周、每月）
特定运动细分

设置

先决条件

Garmin Connect帐户：具有兼容Garmin设备数据的活动帐户
Node.js：版本20或更高
MCP客户端：Claude Desktop、Claude Code或其他MCP兼容应用程序

安装

选项1：与npx一起使用（推荐）

无需安装！直接在MCP客户端中配置：

克劳德桌面 (~/Library/Application Support/Claude/claude_desktop_config.json 在macOS或 %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

{
  "mcpServers": {
    "garmin-connect": {
      "command": "npx",
      "args": ["-y", "garmin-connect-mcp@latest"],
      "env": {
        "GARMIN_USERNAME": "your_username",
        "GARMIN_PASSWORD": "your_password"
      }
    }
  }
}

克劳德代码:

使用Claude Code CLI（推荐）：

claude mcp add garmin-connect npx garmin-connect-mcp@latest \
  --env GARMIN_USERNAME=your_username \
  --env GARMIN_PASSWORD=your_password

或手动配置(.claude/mcp.json 在您的项目中）：

{
  "mcpServers": {
    "garmin-connect": {
      "command": "npx",
      "args": ["-y", "garmin-connect-mcp@latest"],
      "env": {
        "GARMIN_USERNAME": "your_username",
        "GARMIN_PASSWORD": "your_password"
      }
    }
  }
}

这 -y flag自动接受npx提示，确保顺利启动。

选项2：全局安装

通过npm全局安装：

npm install -g garmin-connect-mcp@latest

然后在没有npx的情况下进行配置：

{
  "mcpServers": {
    "garmin-connect": {
      "command": "garmin-connect-mcp",
      "env": {
        "GARMIN_USERNAME": "your_username",
        "GARMIN_PASSWORD": "your_password"
      }
    }
  }
}

方案3：地方发展

对于开发或测试本地更改：

git clone <repository-url>
cd garmin-connect-mcp
pnpm install
pnpm build

配置绝对路径：

{
  "mcpServers": {
    "garmin-connect": {
      "command": "node",
      "args": ["/absolute/path/to/garmin-connect-mcp/dist/index.js"],
      "env": {
        "GARMIN_USERNAME": "your_username",
        "GARMIN_PASSWORD": "your_password"
      }
    }
  }
}

或者使用 .env 文件：

{
  "mcpServers": {
    "garmin-connect": {
      "command": "node",
      "args": ["/absolute/path/to/garmin-connect-mcp/dist/index.js"],
      "envFile": "/absolute/path/to/garmin-connect-mcp/.env"
    }
  }
}

可用工具

概述工具

`get_daily_overview`

在一次通话中获得全面的每日总结，包括睡眠、活动和健康指标。

参数：

date （可选）：日期 YYYY-MM-DD 格式（默认为今天）

例子：

Show me my daily overview for yesterday

答复包括：

睡眠总结（持续时间、质量、阶段）
活动摘要（计数、总持续时间、距离）
健康指标（步数、心率、压力、身体电池）

睡眠工具

`get_sleep_data`

获取详细的睡眠信息，包括睡眠阶段、运动和质量指标。

参数：

date （可选）：日期 YYYY-MM-DD 格式（默认为今天）
summary （可选）：仅返回摘要数据（默认值：false）
fields （可选）：要包括的特定字段（例如。， ['dailySleepDTO', 'wellnessEpochSummaryDTO'])

例子：

Get my detailed sleep data for 2025-01-15
Show me a sleep summary for last night

答复包括：

总睡眠时间
睡眠阶段（深度、轻度、快速眼动、清醒）及其持续时间
睡眠评分和质量评级
开始/结束时间
运动数据（当 summary: false)

`get_sleep_duration`

快速访问特定日期的总睡眠时间。

参数：

date （可选）：日期 YYYY-MM-DD 格式（默认为今天）

例子：

How many hours did I sleep last night?

健康指标工具

`get_health_metrics`

获取特定日期的聚合健康指标。

参数：

date （可选）：日期 YYYY-MM-DD 格式（默认为今天）
metrics （可选）：特定指标数组 ['steps', 'weight', 'heart_rate', 'stress', 'body_battery'] （默认为全部）

例子：

What are my health metrics for today?
Show me just my steps and heart rate for yesterday

答复包括：

步数数据（计数、目标、距离）
心率（静息、最大、区域）
应力水平
车身电池百分比
体重和身体成分

`get_steps_data`

获取详细的步数和活动数据。

参数：

date （可选）：日期 YYYY-MM-DD 格式（默认为今天）
summary （可选）：仅返回摘要数据（默认值：false）

例子：

Show me my step data for today
How many steps did I take yesterday?

答复包括：

总步骤数
每日目标和进度百分比
覆盖的距离
活动时间
每小时细分（当 summary: false)

`get_heart_rate_data`

获取详细的心率测量值和区域数据。

参数：

date （可选）：日期 YYYY-MM-DD 格式（默认为今天）
summary （可选）：仅返回摘要数据（默认值：false）

例子：

What was my heart rate today?
Show me my heart rate zones for yesterday

答复包括：

静息心率
最大心率
平均心率
心率区域和每个区域的时间
时间序列测量（当 summary: false)

`get_weight_data`

获取体重和身体成分数据。

参数：

date （可选）：日期 YYYY-MM-DD 格式（默认为今天）

例子：

What's my current weight?
Show me my weight for last week

答复包括：

重量（千克/磅）
身体质量指数
体脂肪率
肌肉质量
体内水分百分比

活动工具

`get_activities`

使用可选的筛选和分页功能获取最近活动的列表。

参数：

start （可选）：分页的起始索引（默认值：0）
limit （可选）：要返回的活动数，最大50（默认值：20）
summary （可选）：返回压缩摘要格式（默认值：false）

例子：

List my last 10 activities
Show me my recent runs
Get activities 20-40 (for pagination)

答复包括：

活动ID和名称
活动类型（跑步、骑自行车、游泳等）
开始时间和持续时间
距离、速度、速度
卡路里和海拔增加
心率数据
分裂和重叠（当 summary: false)

`get_activity_details`

获取特定活动的全面信息。

参数：

activityId （必填）：活动的唯一ID

例子：

Show me details for activity 12345678
Give me the full breakdown of my last run

答复包括：

完整的活动元数据
详细的劈叉和圈数
心率区域
节奏、功率和其他传感器数据
GPS/路线信息
天气情况

培训卷工具

`get_weekly_volume`

获取特定ISO周的汇总培训量。

参数：

year （可选）：年份（默认为当前年份）
week （可选）：ISO周数1-53（默认为当前周）
includeActivityBreakdown （可选）：包括每项运动的细分（默认值：true）
includeTrends （可选）：与上周比较（默认值：false）
maxActivities （可选）：要处理的最大活动数，最多2000（默认值：1000）
activityTypes （可选）：按活动类型过滤（例如。， ['running', 'cycling'])

例子：

What was my training volume this week?
Show me week 42 of 2024 with trends
Compare my running volume this week vs last week

答复包括：

周数和日期范围
总指标（持续时间、距离、卡路里、海拔高度）
活动计数
按活动类型细分
每周趋势（当 includeTrends: true)

`get_monthly_volume`

获取特定月份的汇总培训量。

参数：

year （可选）：年份（默认为当前年份）
month （可选）：月份编号1-12（默认为当月）
includeActivityBreakdown （可选）：包括每项运动的细分（默认值：true）
includeTrends （可选）：与上月比较（默认值：false）
maxActivities （可选）：要处理的最大活动数，最多2000（默认值：1000）
activityTypes （可选）：按活动类型筛选

例子：

What was my training volume in January?
Show me this month's cycling volume
Compare my training this month vs last month

答复包括：

月份名称和日期范围
总指标（持续时间、距离、卡路里、海拔高度）
活动计数
按活动类型细分
逐月趋势

`get_custom_range_volume`

获取任何自定义日期范围（最多365天）的培训量。

参数：

dateRange （必填）：日期范围为 YYYY-MM-DD/YYYY-MM-DD
includeActivityBreakdown （可选）：包括每项运动的细分（默认值：true）
includeDailyBreakdown （可选）：包括每日细分（默认值：false）
maxActivities （可选）：要处理的最大活动数，最多2000（默认值：1000）
activityTypes （可选）：按活动类型筛选

例子：

What was my training volume from 2025-01-01 to 2025-01-31?
Show me my running volume for the last 90 days
Give me a daily breakdown for the past 2 weeks

答复包括：

日期范围和时段长度
整个范围内的总指标
活动计数
按活动类型细分
每日细分（当 includeDailyBreakdown: true)

用法示例

快速健康检查

What's my daily overview for today?

睡眠分析

Show me my sleep quality for the past week
Compare my deep sleep from Monday vs Tuesday

培训见解

How much did I run this month?
Compare my weekly volume: this week vs last week
What's my total training time for Q1 2025?

活动探索

List my last 20 activities
Show me all my runs from January with heart rate data
What was my fastest 5K in the past 6 months?

高级查询

Get my weekly running volume with trends for week 15 of 2025
Show me daily breakdown of cycling for 2025-03-01/2025-03-31
What are my health metrics (just steps and heart rate) for yesterday?

高级功能

分页

对于大型活动列表，请使用分页：

// Get activities 0-49
get_activities({ start: 0, limit: 50 })

// Get activities 50-99
get_activities({ start: 50, limit: 50 })

活动类型筛选

按特定运动筛选训练量：

get_weekly_volume({
  activityTypes: ['running', 'cycling'],
  includeTrends: true
})

趋势分析

比较时段以跟踪进度：

// Week-over-week comparison
get_weekly_volume({ includeTrends: true })

// Month-over-month comparison
get_monthly_volume({ includeTrends: true })

摘要模式与详细模式

控制响应大小和详细程度：

// Quick summary
get_sleep_data({ summary: true })

// Full detailed breakdown with time-series
get_sleep_data({ summary: false })

响应大小管理

服务器会自动验证响应大小，并在数据超过限制时提供回退摘要。对于较大的日期范围，请考虑：

使用 summary: true 模式
按特定活动类型筛选
缩小日期范围
禁用详细细分

发展

命令

# Development
pnpm install          # Install dependencies
pnpm build            # Build for production
pnpm dev              # Watch mode with auto-rebuild

# Quality Checks
pnpm typecheck        # Run TypeScript type checking
pnpm lint             # Lint code
pnpm lint:fix         # Auto-fix linting issues

# Testing
pnpm test             # Run tests in watch mode
pnpm test:run         # Run tests once
pnpm test:coverage    # Generate coverage report

项目结构

garmin-connect-mcp/
├── src/
│   ├── client/           # Garmin Connect API client
│   ├── tools/            # MCP tool implementations
│   │   ├── overview-tools.ts
│   │   ├── sleep-tools.ts
│   │   ├── health-tools.ts
│   │   ├── activity-tools.ts
│   │   └── activity-volume-tools.ts
│   ├── types/            # TypeScript type definitions
│   ├── utils/            # Helper functions
│   └── index.ts          # Main server entry point
├── dist/                 # Built output
└── __tests__/            # Test files

运行测试

# Run all tests
pnpm test:run

# Run with coverage
pnpm test:coverage

# Watch mode for development
pnpm test

安全

凭据管理

最佳实践：

✅ 使用环境变量作为凭据
✅ 使用 .env 文件（确保 .env 在...里 .gitignore)
✅ 使用MCP配置 env 或 envFile 选项
❌ 切勿在配置文件中硬编码凭据
❌ 从不将凭据提交到版本控制

环境变量

创建一个 .env 项目根目录中的文件：

GARMIN_USERNAME=your_username
GARMIN_PASSWORD=your_password

本地测试

对于当地发展，使用 .mcp.json （忽略）：

{
  "mcpServers": {
    "garmin-connect": {
      "command": "node",
      "args": ["./dist/index.js"],
      "envFile": ".env"
    }
  }
}

API费率限制

服务器包括Garmin Connect API的自动速率限制和错误处理：

批处理请求之间的小延迟（100ms）
对失败的请求进行优雅的错误处理
最大活动限制，以防止API不堪重负

故障排除

常见问题

认证失败

验证中的凭据 .env 文件
检查MCP配置点是否正确 .env 或具有正确的 env 价值观
确保Garmin帐户处于活动状态且可访问

未返回数据

验证您的Garmin设备最近是否已同步
检查您是否使用实际数据查询日期
确保您的Garmin帐户具有请求的数据类型

响应太大

使用 summary: true 浓缩结果
减少卷查询的日期范围
按特定活动类型筛选
禁用详细细分(includeActivityBreakdown: false)

服务器未启动

确保Node.js版本为20或更高
跑 pnpm build 更改后重建
检查服务器日志中的身份验证错误

贡献

欢迎投稿！请确保：

所有测试均通过(pnpm test:run)
类型检查通过(pnpm typecheck)
代码遵循现有的样式指南
新功能包括测试

许可证

麻省理工学院

版本

当前版本：0.1.0

有关更新和更改日志，请参阅发布页面.

使用说明

Garmin Connect MCP服务器

目录

概述

特性

🌙 睡眠分析

💪 健康指标

🏃 活动跟踪

📊 培训量分析

设置

先决条件

安装

选项1：与npx一起使用（推荐）

选项2：全局安装

方案3：地方发展

可用工具

概述工具

get_daily_overview

睡眠工具

get_sleep_data

get_sleep_duration

健康指标工具

get_health_metrics

get_steps_data

get_heart_rate_data

get_weight_data

活动工具

get_activities

get_activity_details

培训卷工具

get_weekly_volume

get_monthly_volume

get_custom_range_volume

用法示例

快速健康检查

睡眠分析

培训见解

活动探索

高级查询

高级功能

分页

活动类型筛选

趋势分析

摘要模式与详细模式

响应大小管理

发展

命令

项目结构

运行测试

安全

凭据管理

环境变量

本地测试

API费率限制

故障排除

常见问题

贡献

许可证

版本

相关 MCP

健康数据查询服务器

健康数据访问服务器

健康数据分析服务

健康数据集成服务器

Oura Ring健康数据分析服务

Garmin Connect MCP服务

`get_daily_overview`

`get_sleep_data`

`get_sleep_duration`

`get_health_metrics`

`get_steps_data`

`get_heart_rate_data`

`get_weight_data`

`get_activities`

`get_activity_details`

`get_weekly_volume`

`get_monthly_volume`

`get_custom_range_volume`