金大哥 - garmin-mcp MCP 详情

article

README

🚀 Garmin MCP 服务器

Garmin MCP 服务器是一个 Webhook 接收器和 MCP（模型上下文协议）服务器，它可以收集 Garmin 健康数据，并通过 OpenAI 的远程 MCP 集成将这些数据提供给 ChatGPT 使用。

✨ 主要特性

Garmin Webhook 接收器：接收来自 Garmin 设备的健康数据。
SQLite 持久化：为保证数据可靠性，将数据存储在 EFS 上的 SQLite 数据库中。
MCP 集成：通过 OpenAI 的远程 MCP 为 ChatGPT 提供健康数据。
AWS 部署：借助 Terraform 基础设施在 ECS Fargate 上运行。
速率限制：防止 Webhook 端点被滥用。

🔧 架构

Garmin 设备 → Webhook → SQLite 数据库 → MCP 服务器 → ChatGPT

📊 收集的数据

每日步数
静息心率
活动消耗的卡路里
睡眠时间
身体能量水平

🚀 快速开始

本地开发

克隆仓库：

git clone https://github.com/yourusername/garmin-mcp.git
cd garmin-mcp

安装依赖：

npm install

设置环境变量：

cp env.example .env
# 使用你的配置编辑 .env

构建并运行：

npm run build
npm start

Docker

docker-compose up --build

本地 HTTPS（Cloudflare 快速隧道）

你可以使用临时公共 HTTPS URL 公开本地服务器（无需 DNS 或账户）：

brew install cloudflared
./scripts/cloudflared-quick.sh

此命令会输出一个 https://<random>.trycloudflare.com 格式的 URL。可使用该 URL 测试以下端点：

Webhook：https://<random>.trycloudflare.com/garmin/webhook
健康检查：https://<random>.trycloudflare.com/healthz

📚 详细文档

环境变量

| 变量 | 描述 | 是否必需 | |------|------|----------| | PORT | 服务器端口（默认：8080） | 否 | | MCP_API_TOKEN | 用于 MCP 认证的 Bearer 令牌 | 是 | | GARMIN_WEBHOOK_SECRET | 用于 Webhook 签名验证的密钥 | 否 | | GARMIN_API_KEY | Garmin 健康 API 密钥 | 否 | | GARMIN_API_SECRET | Garmin 健康 API 密钥 | 否 |

API 端点

Webhook

POST /garmin/webhook - 接收 Garmin 健康数据

MCP（模型上下文协议）

GET /mcp/tools - 列出可用工具
POST /mcp/tools/call - 执行工具
GET /mcp/sse - 服务器发送事件端点

健康检查

GET /healthz - 健康检查端点

MCP 工具

`garmin.getDailySummary`

获取用户某一天的每日健康摘要。 参数：

user_id（字符串，必需）：用户标识符
date（字符串，可选）：日期，格式为 YYYY-MM-DD（默认为今天）

`garmin.getRecentDays`

获取用户最近 N 天的健康数据。 参数：

user_id（字符串，必需）：用户标识符
days（数字，可选）：要获取的天数（默认：7）

🔄 版本控制与部署

版本控制策略

我们使用基于 Git 的版本控制来管理 Docker 镜像：

Git 标签：创建语义化版本标签（例如，v1.0.0、v1.1.0）
Docker 标签：镜像同时使用 Git 版本和 latest 标签
回滚：通过更新 ECS 任务定义以使用先前版本，可轻松实现回滚

创建版本发布

# 1. 为版本发布创建 Git 标签
git tag v1.0.0

# 2. 构建并推送带有版本号的镜像
cd terraform
./build-and-push.sh

# 3. 部署到 ECS
aws ecs update-service --cluster garmin-mcp-cluster --service garmin-mcp-service --force-new-deployment

版本历史

v0.1.0：初始版本，支持 SQLite 持久化和集成测试
下一个版本：v1.0.0 - 支持 Cloudflare 隧道部署，可用于生产环境

回滚流程

# 列出 ECR 中可用的版本
aws ecr describe-images --repository-name garmin-mcp --query 'imageDetails[*].imageTags' --output table

# 更新任务定义以使用特定版本
aws ecs update-service --cluster garmin-mcp-cluster --service garmin-mcp-service --task-definition garmin-mcp-task:REVISION_NUMBER

部署

使用 Terraform 在 AWS 上部署（成本优化 - 约 9 美元/月）

我们的基础设施采用成本优化架构，并使用 Cloudflare 隧道实现安全访问：

ECS Fargate：单个任务，0.25 vCPU，0.5GB 内存
无 NAT 网关：仅使用公共 IP 进行出站连接，每月节省约 33 美元
Cloudflare 隧道：提供安全的 HTTPS 访问，无需公共入站流量
EFS 存储：用于 SQLite 数据库持久化（约 0.30 美元/月）

前提条件

Cloudflare 账户：创建隧道并获取隧道令牌
AWS 凭证：配置 AWS CLI 访问权限
域名：可选 - 用于自定义主机名，替代 trycloudflare.com

部署步骤

创建 Cloudflare 隧道：

# 安装 cloudflared
brew install cloudflared

# 登录 Cloudflare
cloudflared tunnel login

# 创建隧道
cloudflared tunnel create garmin-mcp

# 获取隧道令牌（保存好）
cloudflared tunnel token garmin-mcp

配置 Terraform：

cd terraform

# 使用你的隧道令牌创建 terraform.tfvars
echo 'cloudflare_tunnel_token = "your-tunnel-token-here"' > terraform.tfvars

部署：

./deploy.sh

配置隧道路由（可选）：

# 用于自定义域名
cloudflared tunnel route dns garmin-mcp webhook.yourdomain.com

安全优势

无公共入站流量：安全组阻止所有传入流量
仅出站连接：任务可以进行出站连接（如 Docker 镜像、Cloudflare）
加密隧道：所有流量通过 Cloudflare 边缘加密
成本效益高：无需 NAT 网关或应用程序负载均衡器

手动部署

构建 Docker 镜像
推送到 ECR
部署到 ECS Fargate

🔒 隐私

这是一个个人非商业项目。有关数据收集和使用的详细信息，请参阅 PRIVACY.md。

📄 许可证

仅供个人使用。本项目不用于商业用途。

🤝 贡献

这是一个个人项目，但欢迎通过问题反馈和讨论提出建议和改进意见。

garmin-mcp