Garmin MCP Server

# Garmin MCP Server A webhook receiver and MCP (Model Context Protocol) server that collects Garmin health data and makes it available to ChatGPT through OpenAI's Remote MCP integration. ## Features - **Garmin Webhook Receiver**: Accepts health data from Garmin devices - **SQLite Persistence**: Stores data in SQLite database on EFS for reliability - **MCP Integration**: Provides health data to ChatGPT via OpenAI's Remote MCP - **AWS Deployment**: Runs on ECS Fargate with Terraform infrastructure - **Rate Limiting**: Protects webhook endpoints from abuse ## Architecture ``` Garmin Device → Webhook → SQLite DB → MCP Server → ChatGPT ``` ## Data Collected - Daily step count - Resting heart rate - Active calories burned - Sleep duration - Body battery levels ## Quick Start ### Local Development 1. Clone the repository: ```bash git clone https://github.com/yourusername/garmin-mcp.git cd garmin-mcp ``` 2. Install dependencies: ```bash npm install ``` 3. Set up environment variables: ```bash cp env.example .env # Edit .env with your configuration ``` 4. Build and run: ```bash npm run build npm start ``` ### Docker ```bash docker-compose up --build ``` ### Local HTTPS (Cloudflare Quick Tunnel) You can expose your local server with a temporary public HTTPS URL (no DNS or account needed): ```bash brew install cloudflared ./scripts/cloudflared-quick.sh ``` This prints a `https://<random>.trycloudflare.com` URL. Use it for testing endpoints: - Webhook: `https://<random>.trycloudflare.com/garmin/webhook` - Health: `https://<random>.trycloudflare.com/healthz` ## Environment Variables | Variable | Description | Required | |----------|-------------|----------| | `PORT` | Server port (default: 8080) | No | | `MCP_API_TOKEN` | Bearer token for MCP authentication | Yes | | `GARMIN_WEBHOOK_SECRET` | Secret for webhook signature verification | No | | `GARMIN_API_KEY` | Garmin Health API key | No | | `GARMIN_API_SECRET` | Garmin Health API secret | No | ## API Endpoints ### Webhook - `POST /garmin/webhook` - Receives Garmin health data ### MCP (Model Context Protocol) - `GET /mcp/tools` - Lists available tools - `POST /mcp/tools/call` - Executes a tool - `GET /mcp/sse` - Server-sent events endpoint ### Health - `GET /healthz` - Health check endpoint ## MCP Tools ### `garmin.getDailySummary` Get daily health summary for a user and date. **Parameters:** - `user_id` (string, required): User identifier - `date` (string, optional): Date in YYYY-MM-DD format (defaults to today) ### `garmin.getRecentDays` Get health data for the last N days. **Parameters:** - `user_id` (string, required): User identifier - `days` (number, optional): Number of days to retrieve (default: 7) ## Versioning & Deployment ### Versioning Strategy We use git-based versioning for Docker images: - **Git Tags**: Create semantic version tags (e.g., `v1.0.0`, `v1.1.0`) - **Docker Tags**: Images are tagged with both the git version and `latest` - **Rollback**: Can easily rollback by updating ECS task definition to use a previous version #### Creating a Release ```bash # 1. Create a git tag for the release git tag v1.0.0 # 2. Build and push with versioning cd terraform ./build-and-push.sh # 3. Deploy to ECS aws ecs update-service --cluster garmin-mcp-cluster --service garmin-mcp-service --force-new-deployment ``` #### Version History - **v0.1.0**: Initial release with SQLite persistence and integration tests - **Next**: `v1.0.0` - Production ready with Cloudflare Tunnel deployment #### Rollback Process ```bash # List available versions in ECR aws ecr describe-images --repository-name garmin-mcp --query 'imageDetails[*].imageTags' --output table # Update task definition to use specific version aws ecs update-service --cluster garmin-mcp-cluster --service garmin-mcp-service --task-definition garmin-mcp-task:REVISION_NUMBER ``` ### Deployment ### AWS with Terraform (Cost Optimized - ~$9/month) Our infrastructure uses a cost-optimized architecture with Cloudflare Tunnel for secure access: - **ECS Fargate**: Single task with 0.25 vCPU, 0.5GB RAM - **No NAT Gateway**: Saves ~$33/month by using public IP for outbound only - **Cloudflare Tunnel**: Provides secure HTTPS access without public inbound traffic - **EFS Storage**: SQLite database persistence (~$0.30/month) #### Prerequisites 1. **Cloudflare Account**: Create a tunnel and get the tunnel token 2. **AWS Credentials**: Configure AWS CLI access 3. **Domain**: Optional - for custom hostname instead of trycloudflare.com #### Deploy Steps 1. **Create Cloudflare Tunnel**: ```bash # Install cloudflared brew install cloudflared # Login to Cloudflare cloudflared tunnel login # Create tunnel cloudflared tunnel create garmin-mcp # Get tunnel token (save this) cloudflared tunnel token garmin-mcp ``` 2. **Configure Terraform**: ```bash cd terraform # Create terraform.tfvars with your tunnel token echo 'cloudflare_tunnel_token = "your-tunnel-token-here"' > terraform.tfvars ``` 3. **Deploy**: ```bash ./deploy.sh ``` 4. **Configure Tunnel Route** (optional): ```bash # For custom domain cloudflared tunnel route dns garmin-mcp webhook.yourdomain.com ``` #### Security Benefits - **No Public Inbound**: Security group blocks all incoming traffic - **Outbound Only**: Task can make outbound connections (Docker images, Cloudflare) - **Encrypted Tunnel**: All traffic encrypted through Cloudflare's edge - **Cost Effective**: No NAT Gateway or ALB required ### Manual Deployment 1. Build the Docker image 2. Push to ECR 3. Deploy to ECS Fargate ## Privacy This is a personal, non-commercial project. See [PRIVACY.md](PRIVACY.md) for details on data collection and usage. ## License Personal use only. This project is not intended for commercial use. ## Contributing This is a personal project, but suggestions and improvements are welcome through issues and discussions.