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

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

Fitness & Performance

Activities

Body Composition

Gear & Profile

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