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

Data Collected

• Daily step count

• Resting heart rate

• Active calories burned

• Sleep duration

• Body battery levels

Quick Start

Local Development

1. Clone the repository:

2. Install dependencies:

3. Set up environment variables:

4. Build and run:

Docker

Local HTTPS (Cloudflare Quick Tunnel)

You can expose your local server with a temporary public HTTPS URL (no DNS or account needed):

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

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

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

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:

   # 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:

   cd terraform # Create terraform.tfvars with your tunnel token echo 'cloudflare_tunnel_token = "your-tunnel-token-here"' > terraform.tfvars

3. Deploy:

   ./deploy.sh

4. Configure Tunnel Route (optional):

   # 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 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.