Garmin MCP

🚀 Garmin MCP Server

Garmin MCP Serverは、Garminの健康データを収集し、OpenAIのRemote MCP統合を通じてChatGPTに提供するWebhookレシーバーとMCP（Model Context Protocol）サーバーです。

✨ 主な機能

• Garmin Webhookレシーバー：Garminデバイスからの健康データを受け取ります。
• SQLiteデータ永続化：信頼性を高めるため、データをEFS上のSQLiteデータベースに保存します。
• MCP統合：OpenAIのRemote MCPを介してChatGPTに健康データを提供します。
• AWSデプロイメント：Terraformインフラストラクチャを使用してECS Fargate上で実行されます。
• レート制限：Webhookエンドポイントを悪用から保護します。

🔧 アーキテクチャ

Garmin Device → Webhook → SQLite DB → MCP Server → 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 Quick Tunnel）

一時的な公開HTTPS URLでローカルサーバーを公開することができます（DNSやアカウントは不要です）：

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

これにより、https://<random>.trycloudflare.comのURLが表示されます。これをエンドポイントのテストに使用します：

• Webhook: https://<random>.trycloudflare.com/garmin/webhook
• ヘルスチェック: https://<random>.trycloudflare.com/healthz

📚 環境変数

📄 APIエンドポイント

Webhook

• POST /garmin/webhook - Garminの健康データを受け取ります。

MCP (Model Context Protocol)

• 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）

📈 バージョニングとデプロイメント

バージョニング戦略

DockerイメージにはGitベースのバージョニングを使用しています：

• 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 Tunnelデプロイで本番環境に対応

ロールバックプロセス

# 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 Tunnelを使用したコスト最適化アーキテクチャを採用しています：

• ECS Fargate: 0.25 vCPU、0.5GB RAMの単一タスク
• NATゲートウェイなし: アウトバウンドのみのパブリックIPを使用することで、月約33ドルを節約します
• Cloudflare Tunnel: パブリックなインバウンドトラフィックなしでセキュアな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ゲートウェイやALBが不要です

手動デプロイ

1. Dockerイメージをビルドします
2. ECRにプッシュします
3. ECS Fargateにデプロイします

🔒 プライバシー

これは個人用の非商用プロジェクトです。データ収集と使用の詳細については、PRIVACY.mdを参照してください。

📄 ライセンス

個人使用のみを許可します。このプロジェクトは商用利用を目的としていません。

🤝 コントリビューション

これは個人プロジェクトですが、問題や議論を通じた提案や改善は歓迎します。