mcp-garmin-connect 0.2.0

LLM-agnostic Garmin Connect MCP server for training, recovery, sleep, stress, VO2 Max, race predictions, and running summaries.

Use the same local Garmin tools from any MCP client — Claude Desktop, Claude Code, Cursor, Continue, Hermes, opencode — or from provider-backed demo agents using DeepSeek, OpenAI, Claude, OpenRouter, or Gemini.

Works With Any MCP Harness

This server implements standard MCP over stdio and Streamable HTTP, so there is no harness-specific adapter to maintain. If your tool speaks MCP, it works:

Any client that supports MCP over stdio or Streamable HTTP can use every tool and prompt in this server with no extra code.

Why This Exists

Most fitness advice from LLMs is generic. This server lets an LLM inspect your real Garmin Connect data first, then answer with context from your activities, recovery markers, HRV, sleep, stress, VO2 Max, and running history.

The core server is provider-neutral. DeepSeek, OpenAI, Claude, OpenRouter, and Gemini integrations are optional demo bridges for clients that do not speak MCP directly.

Features

• 15 Garmin tools and 4 prompt templates for training and recovery analysis.
• Local MCP server over stdio or Streamable HTTP (/mcp).
• Endpoint-level TTL cache with single-flight factories — concurrent tool calls share one Garmin request instead of stampeding the API.
• Global request concurrency cap so parallel snapshots stay within a safe request rate.
• Partial-error reporting — composite tools include an errors array when an endpoint fails, instead of silently returning nulls.
• Provider demo bridge for deepseek, openai, claude, openrouter, and gemini.
• Explicit opt-in before Garmin health/activity data is sent to any external LLM provider.
• Mocked test suite plus optional live Garmin smoke tests.

Quick Start

uv sync
cp .env.example .env

Set Garmin credentials in .env:

GARMIN_EMAIL=you@example.com
GARMIN_PASSWORD=your-password

Authenticate once (interactive MFA supported):

uv run garmin-mcp login
uv run garmin-mcp doctor --live

List available MCP tools, then run the server:

uv run garmin-mcp tools
uv run garmin-mcp serve --transport stdio

HTTP transport:

uv run garmin-mcp serve --transport http --host 127.0.0.1 --port 8765
# clients connect to http://127.0.0.1:8765/mcp

Windows (PowerShell) equivalents: uv sync, Copy-Item .env.example .env, notepad .env, then the same uv run garmin-mcp ... commands.

MCP Client Setup

Generic stdio config:

{
  "mcpServers": {
    "garmin": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-garmin-connect",
        "run",
        "garmin-mcp",
        "serve",
        "--transport",
        "stdio"
      ]
    }
  }
}

opencode (opencode.json):

{
  "mcp": {
    "garmin": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "/path/to/mcp-garmin-connect",
        "run",
        "garmin-mcp",
        "serve",
        "--transport",
        "stdio"
      ],
      "enabled": true
    }
  }
}

Per-client examples (Claude Desktop, Claude Code, Cursor, Continue, Hermes, generic stdio/HTTP) live in docs/clients.

MCP Tools

MCP Prompts

• recovery_check
• weekly_training_review
• activity_analysis
• race_plan_context

Configuration

All settings come from environment variables (.env is loaded automatically).

Provider bridge variables (optional): DEEPSEEK_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY, plus the matching *_BASE_URL and *_MODEL overrides.

How It Stays Fast And Quiet

• Endpoint-level cache. Sleeping, stress, RHR, and activity fetches are cached per day/limit and shared across every tool that needs them — a get_full_snapshot burst reuses the same responses instead of refetching.
• Single-flight. If two tool calls ask for the same missing key, only one hits Garmin; the other waits and reuses the result.
• Failures are never cached. A failed endpoint is retried on the next call.
• Concurrency cap. All outbound Garmin calls pass through one bounded semaphore (GARMIN_MAX_CONCURRENCY) so parallel sections cannot flood the API.
• Visible partial failures. When an optional endpoint fails, composite tools add an errors array (source + exception) to their output.

Provider Demo Agents

Provider API access may require a paid account or credits even if the provider's web app has a free tier.

DEEPSEEK_API_KEY=sk-...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
OPENROUTER_API_KEY=sk-or-...
GEMINI_API_KEY=...

uv run garmin-mcp ask "How is my recovery today?" --provider deepseek --allow-external-health-data
uv run garmin-mcp ask "Summarize my running for 90 days." --provider openai --allow-external-health-data
uv run garmin-mcp ask "What should I focus on this week?" --provider claude --allow-external-health-data

The --allow-external-health-data flag is required because Garmin tool results can be sent to the selected provider.

Privacy And Safety

• Your .env file and Garmin token cache stay local and are ignored by git.
• MCP clients that run locally can call Garmin tools without sending provider API keys to this project.
• Provider demo commands such as garmin-mcp ask can send Garmin health/activity results to the selected LLM provider, so the CLI requires --allow-external-health-data.
• get_zones returns only zone/threshold fields from the Garmin profile, not the raw profile (gender, birth date, weight, and similar PII are trimmed).

Testing

uv run garmin-mcp doctor
uv run garmin-mcp doctor --live
uv run garmin-mcp tools
uv run ruff check .
uv run pytest

CI runs on Linux (Python 3.11, 3.12, 3.13) and Windows (3.12). Optional live tests are gated and never run in CI:

$env:GARMIN_LIVE_TEST = "1"
uv run pytest tests/live

Troubleshooting

• Garmin rate-limited the request — lower GARMIN_MAX_CONCURRENCY (for example to 3) and retry after a few minutes.
• Garmin authentication failed — check GARMIN_EMAIL/GARMIN_PASSWORD, then run uv run garmin-mcp login from a real terminal (MFA prompts need interactive input).
• A tool returns errors — the array names the endpoint that failed; the rest of the payload is still valid partial data.

Garmin Disclaimer

This project uses the community garminconnect Python package and Garmin Connect endpoints. Garmin Connect is not a public API for individual open-source projects, and authentication or endpoint behavior may change without notice.

Some metrics depend on Garmin device capabilities. For example, a device may expose VO2 Max and Training Effect but not native Garmin Training Load or Training Status. Zone availability depends on what the Garmin user settings endpoint exposes for your account.

License

This project is licensed under the MIT License.

Made by kavakoss. Inspired by Jack-Abyss/claude-garmin, with a clean-room implementation focused on LLM-agnostic MCP usage.