GC-MCP

Disclaimer: GC-MCP is an independent, community-made project. It is not affiliated with, endorsed by, or created by Garmin Ltd. Garmin and Garmin Connect are trademarks of Garmin Ltd.

A Model Context Protocol server that connects AI assistants to your Garmin Connect account. Ask about your health metrics, training load, activities, and trends — directly from conversation.

Installation (Required)

The MCP server must be installed before anything else — including the gc-coach plugin — will work.

Run this in your terminal:

npx @ace4seven/gc-mcp setup

The wizard will:

1. Ask for your Garmin Connect email and password
2. Save authentication tokens to ~/.gc-mcp/ on your machine
3. Detect all installed AI clients and configure each one automatically

Then restart any configured AI client — you're done.

Supported clients: Claude Desktop, Cursor, Windsurf, VS Code, Zed, Claude Code CLI

Re-authenticate when tokens expire

npx @ace4seven/gc-mcp login

What You Can Ask

Once configured, ask your AI assistant things like:

• "How was my sleep last week?"
• "Show me my HRV trend for the past 30 days"
• "What was my resting heart rate on Monday?"
• "List my last 10 runs with pace and distance"

gc-coach Plugin (Optional)

An optional Claude Code plugin that turns Claude into a personalised fitness coach with persistent memory, daily readiness decisions, weekly planning, and automatic red-flag detection.

Requires the MCP server to be installed first (see Installation above).

Install

/plugin marketplace add ace4seven/GC-MCP
/plugin install gc-coach@gc-mcp-marketplace

Slash Commands

| Command | Description | |---|---| | /coach-onboard | First-run setup. Infers an athlete profile from 90 days of Garmin data, confirms with 5 questions, and writes a conservative starter training block. | | /coach-today | Morning decision. Reads today's readiness, HRV, sleep, and body battery; cross-checks the weekly plan; outputs one prescription + fallback. | | /coach-checkin | Daily log. Asks energy, soreness, sleep, session done, and RPE in a single prompt. Detects patterns and opens flags automatically. | | /coach-plan-week | Builds a periodised Monday–Sunday week with session rationale. Saves to weekly-plan.md. | | /coach-review | Weekly retrospective. Reports adherence, load trajectory, opened/closed flags, and exactly one thing to change next week. |

State Files

All coaching state is stored locally in ~/.gc-mcp/coach/ — no cloud sync.

~/.gc-mcp/coach/
├── profile.json          # Athlete profile (modalities, baselines, voice prefs)
├── goals.md              # Goals in the athlete's own words
├── current-block.md      # Active training block description
├── weekly-plan.md        # Current week's session plan
├── flags.md              # Active and closed red flags
├── daily-log/
│   └── YYYY-MM-DD.md     # Per-day check-in
└── history/
    └── YYYY-Wnn-review.md  # Weekly retrospective archive

Available Tools

Daily Health

| Tool | Description | Parameters | |---|---|---| | get_daily_summary | Steps, calories, floors, active minutes, and distance | start_date?, end_date? | | get_heart_rate | Resting heart rate and intraday HR curve | start_date?, end_date? | | get_stress | Average/max stress levels and timeline | start_date?, end_date? | | get_body_battery | Energy charge/drain curve | start_date?, end_date? | | get_sleep_data | Deep/light/REM/awake breakdown, sleep score, SpO2 | start_date?, end_date? | | get_hrv_status | Nightly HRV score and 5-night rolling average | start_date?, end_date? | | get_respiration | Breathing rate throughout the day | start_date?, end_date? | | get_spo2 | Blood oxygen readings | start_date?, end_date? | | get_hydration | Water intake log | start_date?, end_date? |

Fitness & Performance

| Tool | Description | Parameters | |---|---|---| | get_training_status | Fitness level: peaking, productive, maintaining, etc. | start_date?, end_date? | | get_training_readiness | Readiness score with contributing factors | start_date?, end_date? | | get_training_load | Acute vs chronic load balance (ACWR) over 28 days | date? | | get_vo2max | VO2 max estimate for running and cycling | date? | | get_race_predictor | Predicted 5K, 10K, half marathon, marathon times | — | | get_personal_records | All-time personal records across all sport types | — |

Activities

| Tool | Description | Parameters | |---|---|---| | list_activities | List activities with summary stats | limit? (1–100), sport_type?, start_date?, end_date? | | get_activity | Full details for a single activity | activity_id (required) | | get_activity_splits | Lap/split data for a single activity | activity_id (required) |

Body Composition

| Tool | Description | Parameters | |---|---|---| | get_body_composition | BMI, body fat percentage, and muscle mass | start_date?, end_date? | | get_weight_history | Weight measurements over a date range | start_date (required), end_date (required) |

Gear & Profile

| Tool | Description | Parameters | |---|---|---| | list_gear | Shoes, bikes, and other gear with usage mileage | — | | get_user_profile | Display name, date of birth, weight, preferred units | — |

Date Range Support

Most tools accept optional start_date and end_date (YYYY-MM-DD format, max 90-day range). Omit both for today's data.

Troubleshooting

"Missing credentials" error — Run npx @ace4seven/gc-mcp login to authenticate.

Tools not appearing — Re-run npx @ace4seven/gc-mcp setup, then fully restart your AI client.

Authentication expired — Run npx @ace4seven/gc-mcp login again and restart your AI client.

"Tool result is too large" — Use a shorter date range, or ask about a specific metric rather than fetching everything at once.

Privacy

• Your Garmin credentials are used only during login and are never stored.
• OAuth tokens are stored locally in ~/.gc-mcp/ on your machine.
• All Garmin API requests are made directly from your machine — no data passes through any intermediary server.

Development

Project Structure

src/
  cli.ts                   # Binary entry point — setup/login/server dispatch
  index.ts                 # MCP server: startServer()
  auth.ts                  # Token I/O: login(), loadClient(), isLoggedIn()
  garmin-client.ts         # One fetch* function per tool + range helpers
  tools.ts                 # MCP tool registration
  coach/
    state.ts               # Coach state I/O (~/.gc-mcp/coach/*)
    load-summary.ts        # ACWR + modality load computation
    readiness-synthesis.ts # Readiness fusion (HRV, sleep, body battery)

plugin/                    # gc-coach Claude Code plugin
  .claude-plugin/
  commands/
  skills/

Commands

npm run build       # Compile TypeScript → dist/
npm run setup       # Run the setup wizard
npm run login       # Re-authenticate with Garmin
npm test            # Run unit tests with Vitest
npx tsc --noEmit    # Type-check without emitting files

Adding a New Tool

1. Add a fetch* function in src/garmin-client.ts
2. Register it in src/tools.ts following the existing try/catch pattern
3. Run npm run build

License

MIT