Garmin MCP

🚀 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

📊 收集的数据

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

🚀 快速开始

本地开发

1. 克隆仓库：

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

2. 安装依赖：

npm install

3. 设置环境变量：

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

4. 构建并运行：

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

📚 详细文档

环境变量

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 美元/月）

前提条件

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

部署步骤

1. 创建 Cloudflare 隧道：

# 安装 cloudflared
brew install cloudflared

# 登录 Cloudflare
cloudflared tunnel login

# 创建隧道
cloudflared tunnel create garmin-mcp

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

2. 配置 Terraform：

cd terraform

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

3. 部署：

./deploy.sh

4. 配置隧道路由（可选）：

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

安全优势

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

手动部署

1. 构建 Docker 镜像
2. 推送到 ECR
3. 部署到 ECS Fargate

🔒 隐私

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

📄 许可证

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

🤝 贡献

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