garmin-grafana-mcp-server

An optional, self-hosted Model Context Protocol (MCP) server that exposes your Garmin training data to AI assistants. It is designed as a companion add-on to the arpanghosh8453/garmin-grafana project and reads directly from the InfluxDB instance that garmin-grafana already manages.

This server is a pure data access layer. It returns raw numbers from InfluxDB. All interpretation, analysis, and planning is delegated to the AI model consuming the tools — this server makes no assumptions about your fitness goals.

---

Table of Contents

• How it fits into the ecosystem
• 🪄 See it in action: The AI Coach
• Prerequisites
• Quick Start (Docker Compose)
• Deployment (Docker — recommended)
• Local Development
• Connecting to an MCP Client
• MCP Tools
• Example prompts
• Configuration reference
• Project structure
• Schema compatibility
• Troubleshooting
• License

---

How it fits into the ecosystem

Garmin Device
      │
      ▼
garmin-grafana         ← you already have this running
  ├─ Garmin API sync
  ├─ InfluxDB (stores your data)
  └─ Grafana (dashboards)

garmin-grafana-mcp-server   ← this repo adds this
  └─ Reads from the same InfluxDB
  └─ Exposes MCP tools to AI clients (Claude, Copilot, etc.)

---

🪄 See it in action: The AI Coach

Because this MCP server provides structured, context-aware data to LLMs like Claude, it acts as a world-class personal coach.

Here is an actual, unedited response from Claude (via Copilot) summarizing a ride by cross-referencing six different MCP tools simultaneously (Activity Details, Training Status, Sleep/Recovery, Training Zones, and Stress):

Prompt: "I just came back from my long Z2 ride. Please assess it in detail against our training plan!"

<details> <summary><b>View Claude's Analysis (Click to expand)</b></summary>

1. SCORECARD vs PLAN

| Metric | Target | Actual | Grade | |---|---|---|---| | Duration | 120–150 min | 137.5 min | ✅ Perfect | | Time in Z1+Z2 | — | 99.4% (130.1 min) | ✅ Excellent | | Max HR | ≤130 (ceiling) | 135 bpm | ⚠️ Brief breach | | HR drift | <5% | -4.5% | ✅ Excellent | | Avg cadence | 85–95 rpm | 74 rpm | ❌ Low |

2. LAP-BY-LAP ANALYSIS

• Laps 3–6 were textbook Z2: HR locked at 121–122 bpm. This is exactly the metabolic zone we wanted.
• No cardiac drift: HR drift = -4.5%. This means your aerobic system handled the load comfortably.
• Cadence averaged 74 rpm — below target (85–95). Next time, focus on spinning a lighter gear to reduce muscular fatigue.

3. TRAINING STATUS & LOAD

• Status remains Productive (code 7).
• ACWR 1.4 is on the higher end of the sweet spot. Be cautious not to spike it further; the next session should be easy.
• Aerobic TE 2.4 with zero anaerobic — exactly the prescribed stimulus.

4. POLARIZATION SHIFT — THE BIG WIN

| Metric | Before today | After today | |---|---|---| | Low intensity (Z1+Z2) | 49.4% | 56.7% |

This single ride shifted your 30-day polarization by +7.3% toward low intensity. Two more clean Z2 rides like this and you'll cross the 65% threshold.

5. RECOMMENDATIONS

Next session:

• If HRV/recovery is good: another 90–120 min strict Z2. Same HR targets.
• Cadence drill: consciously target 85+ rpm in the main block. Use a lighter gear and focus on pedal circles.

</details>

---

Prerequisites

| Requirement | Notes | |---|---| | garmin-grafana | Must already be running and populated | | Docker & Docker Compose | For the recommended deployment path | | Python 3.11+ | For local development only |

---

Quick Start (Docker Compose)

If you just want to run the pre-built image alongside your existing garmin-grafana stack, create a docker-compose.yml with the snippet below. No need to clone this repository.

services:
  garmin-grafana-mcp-server:
    image: ghcr.io/ghighi3f/garmin-grafana-mcp-server:latest
    container_name: garmin-grafana-mcp-server
    restart: unless-stopped
    ports:
      - "8765:8765"
    environment:
      # ── Required ─────────────────────────────────────────────
      # Connection to the InfluxDB instance managed by garmin-grafana.
      INFLUXDB_HOST: influxdb            # container name on the shared Docker network
      INFLUXDB_PORT: 8086
      INFLUXDB_DATABASE: GarminStats     # database name from your garmin-grafana .env
      INFLUXDB_USERNAME: admin           # InfluxDB v1 credentials
      INFLUXDB_PASSWORD: adminpassword   # ← change to your actual password

      # ── InfluxDB v2 only (uncomment if you run v2) ──────────
      # INFLUXDB_VERSION: 2
      # INFLUXDB_TOKEN: "your-influxdb-token"
      # INFLUXDB_ORG: "your-org"

      # ── Optional: override schema names ─────────────────────
      # Only needed if your garmin-grafana uses non-default measurement
      # or field names. The defaults match the standard garmin-grafana schema.
      #
      # Measurement names:
      # MEASUREMENT_ACTIVITIES: ActivitySummary
      # MEASUREMENT_DAILY_STATS: DailyStats
      # MEASUREMENT_SLEEP_SUMMARY: SleepSummary
      # MEASUREMENT_ACTIVITY_SESSION: ActivitySession
      # MEASUREMENT_ACTIVITY_LAP: ActivityLap
      # MEASUREMENT_RESTING_HR: DailyStats
      # MEASUREMENT_HRV: HRV_Intraday
      # MEASUREMENT_VO2_MAX: VO2_Max
      # MEASUREMENT_RACE_PREDICTIONS: RacePredictions
      # MEASUREMENT_BODY_COMPOSITION: BodyComposition
      #
      # Field names:
      # FIELD_RESTING_HR: restingHeartRate
      # FIELD_HRV: hrvValue
      # FIELD_VO2_MAX_RUNNING: VO2_max_value
      # FIELD_VO2_MAX_CYCLING: VO2_max_value_cycling
      # FIELD_RACE_5K: time5K
      # FIELD_RACE_10K: time10K
      # FIELD_RACE_HALF: timeHalfMarathon
      # FIELD_RACE_MARATHON: timeMarathon
      # FIELD_WEIGHT: weight
      # FIELD_HR_ZONE_1: hrTimeInZone_1
      # FIELD_HR_ZONE_2: hrTimeInZone_2
      # FIELD_HR_ZONE_3: hrTimeInZone_3
      # FIELD_HR_ZONE_4: hrTimeInZone_4
      # FIELD_HR_ZONE_5: hrTimeInZone_5
      #
      # Training Status & Readiness (garmin-grafana v0.4.0+):
      # MEASUREMENT_TRAINING_STATUS: TrainingStatus
      # MEASUREMENT_TRAINING_READINESS: TrainingReadiness
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8765/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

networks:
  default:
    external: true
    name: garmin-grafana_default   # ← must match your garmin-grafana network

Then start it:

docker compose up -d
curl http://localhost:8765/health

Tip: The only variables most users need to change are INFLUXDB_PASSWORD and possibly INFLUXDB_DATABASE. All schema variables have sensible defaults that match the standard garmin-grafana InfluxDB schema out of the box.

---

Deployment (Docker — recommended)

This is the recommended way to run the server alongside your existing garmin-grafana stack.

1. Clone this repository

git clone https://github.com/ghighi3f/garmin-grafana-mcp-server.git
cd garmin-grafana-mcp-server

2. Configure environment variables

cp .env.example .env

Edit .env to match your garmin-grafana setup. The most important values:

| Variable | Default | Description | |---|---|---| | INFLUXDB_HOST | influxdb | Container name of the InfluxDB service inside the garmin-grafana network. Override in .env only if your service is named differently. | | INFLUXDB_PORT | 8086 | InfluxDB port (usually unchanged) | | INFLUXDB_DATABASE | GarminStats | Database name set in your garmin-grafana config | | INFLUXDB_USERNAME | admin | InfluxDB username from your garmin-grafana .env | | INFLUXDB_PASSWORD | (see .env.example) | InfluxDB password from your garmin-grafana .env | | INFLUXDB_VERSION | 1 | 1 for InfluxDB v1; 2 for InfluxDB v2 | | MCP_PORT | 8765 | Port the MCP server listens on | | QUERY_TIMEZONE | UTC | IANA timezone — must match USER_TIMEZONE in garmin-grafana (see Timezone) |

Note: INFLUXDB_HOST is overridden to influxdb directly in docker-compose.yml so the container resolves the InfluxDB service by its Docker network name. You do not need to set it in .env for the Docker deployment.

3. Identify your garmin-grafana Docker network

The docker-compose.yml in this repo connects to the same Docker network that garmin-grafana creates. By default that network is named garmin-grafana_default.

Verify the network name:

docker network ls | grep garmin

If the name differs from garmin-grafana_default, edit the networks section at the bottom of docker-compose.yml:

networks:
  default:
    external: true
    name: your-actual-network-name   # ← change this

4. Start the server

docker compose up -d

Verify it is running:

curl http://localhost:8765/health

Expected response:

{
  "influxdb": "connected",
  "last_activity_timestamp": "2026-03-17T07:30:00+00:00",
  "measurements_found": ["ActivitySummary", "DailyStats", "SleepSummary", "..."],
  "mcp_endpoint": "http://localhost:8765/mcp",
  "sse_endpoint": "http://localhost:8765/sse"
}

---

Local Development

If you want to run the MCP server directly on your host machine (outside Docker) during development, the server process needs to reach InfluxDB on port 8086. Since InfluxDB is inside a Docker network, you must expose its port to the host.

Step 1: Expose InfluxDB port in your garmin-grafana docker-compose.yml

Open the garmin-grafana docker-compose.yml and add a ports mapping to the influxdb service:

# In your garmin-grafana docker-compose.yml:
services:
  influxdb:
    image: influxdb:1.8
    ports:
      - "8086:8086"   # ← add this line
    # ... rest of your config

Then restart the garmin-grafana stack:

docker compose down && docker compose up -d

Step 2: Set up the Python environment

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

For InfluxDB v2, also install:

pip install influxdb-client

Step 3: Configure for local access

cp .env.example .env

Edit .env and set:

INFLUXDB_HOST=localhost   # reach InfluxDB via the exposed host port
INFLUXDB_PORT=8086

Step 4: Run the server

python server.py

You should see:

============================================================
  Garmin MCP Server
============================================================
  InfluxDB   : localhost:8086/GarminStats
  Measurements: ['ActivitySummary', 'DailyStats', ...]
  Transports : HTTP + SSE (always active)
  /mcp  (Streamable HTTP) : http://localhost:8765/mcp
  /sse  (SSE, deprecated) : http://localhost:8765/sse
  /health                 : http://localhost:8765/health
============================================================

---

Connecting to an MCP Client

All HTTP transports are always active simultaneously — no MCP_TRANSPORT configuration needed for HTTP deployments. Point your client at the right URL and go.

---

Perplexity Mac / Legacy SSE clients

Note: SSE transport is deprecated in the MCP specification. Kept for backward compatibility — prefer Streamable HTTP for new integrations.

{
  "mcpServers": {
    "garmin": {
      "type": "sse",
      "url": "http://<your-host>:8765/sse"
    }
  }
}

---

ChatGPT / VS Code / Modern clients (St