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。

📄 許可證

僅供個人使用。本項目不用於商業用途。

🤝 貢獻

這是一個個人項目，但歡迎通過問題反饋和討論提出建議和改進意見。