Skip to main content
Glama
Garmin Open MCP

Garmin Open MCP

by limited

Garmin Open MCP

CI

An unofficial, free, self-hosted bridge from Garmin Connect to MCP clients and ChatGPT mobile.

Not affiliated with or endorsed by Garmin. This project uses undocumented Garmin Connect consumer endpoints. They can change or stop working without notice.

Features

  • Interactive Garmin login with MFA through python-garminconnect

  • Garmin credentials are discarded after login; session tokens are stored with private filesystem permissions

  • Local SQLite cache for health summaries and activities

  • 11 focused MCP tools over Streamable HTTP or stdio

  • REST/OpenAPI adapter for ChatGPT GPT Actions on iOS and Android

  • Static single-user API key protecting remote endpoints

  • Docker, systemd, and native Python deployment options

Related MCP server: garth-mcp-server

Quick start

Requires Python 3.12+ and uv.

git clone <repository-url> garmin-open-mcp
cd garmin-open-mcp
uv sync
uv run garmin-open-mcp init
uv run garmin-open-mcp login
uv run garmin-open-mcp sync --days 7
uv run garmin-open-mcp serve

Open http://localhost:8000.

Private data defaults to:

~/.local/share/garmin-open-mcp/
├── api-key
├── garmin.sqlite3
└── tokens/

Override it with GARMIN_MCP_DATA_DIR.

CLI

garmin-open-mcp init
garmin-open-mcp login
garmin-open-mcp logout
garmin-open-mcp status --verify
garmin-open-mcp doctor
garmin-open-mcp sync --days 7
garmin-open-mcp show-api-key
garmin-open-mcp serve
garmin-open-mcp stdio

The login command accepts the Garmin password only in the local terminal. The password is not written to config, logs, or SQLite. Garmin session token files are set to mode 0600 where the platform supports it.

MCP

Local stdio

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

Remote Streamable HTTP

Endpoint:

https://your-server.example/mcp

Send the key printed by garmin-open-mcp show-api-key as either:

Authorization: Bearer YOUR_KEY

or:

X-API-Key: YOUR_KEY

The initial release uses a static single-user bearer key, not a full OAuth authorization server. MCP clients that cannot supply custom authorization headers should use stdio or the REST/GPT Actions adapter.

ChatGPT mobile setup

Custom MCP servers are not currently available directly in the ChatGPT mobile app. The included OpenAPI adapter exposes the same service to a private custom GPT:

  1. Deploy this server at a stable HTTPS URL.

  2. On ChatGPT web, create a GPT.

  3. Add an Action and import https://your-server.example/openapi.json.

  4. Select API key authentication.

  5. Configure a custom header named X-API-Key.

  6. Enter the value from garmin-open-mcp show-api-key.

  7. Use https://your-server.example/privacy as the privacy-policy URL.

  8. Keep the GPT private, save it, then open it from ChatGPT on iOS or Android.

Suggested GPT instructions are in GPT_INSTRUCTIONS.md.

REST API

Interactive docs are at /docs. Useful endpoints include:

GET  /api/v1/status
POST /api/v1/sync
GET  /api/v1/day/{day}
GET  /api/v1/sleep/{day}
GET  /api/v1/activities
GET  /api/v1/activities/{activity_id}
GET  /api/v1/training/{day}
GET  /api/v1/body
GET  /api/v1/trends
GET  /api/v1/compare
GET  /api/v1/recent

All /api/v1 endpoints require X-API-Key.

MCP tools

  • garmin_connection_status

  • garmin_sync

  • garmin_get_day

  • garmin_get_sleep

  • garmin_list_activities

  • garmin_get_activity

  • garmin_get_training_status

  • garmin_get_body_metrics

  • garmin_get_trends

  • garmin_compare_periods

  • garmin_recent_overview

The MVP is read-only with respect to Garmin. garmin_sync writes only to the local cache.

Configuration

Environment variable

Default

Purpose

GARMIN_MCP_DATA_DIR

~/.local/share/garmin-open-mcp

Private data and token directory

GARMIN_MCP_HOST

0.0.0.0

Bind address

GARMIN_MCP_PORT

8000

HTTP port

GARMIN_MCP_PUBLIC_URL

unset

Public HTTPS URL and MCP Host allowlist

GARMIN_MCP_API_KEY

generated file

Override the single-user API key

GARMIN_MCP_MAX_SYNC_DAYS

31

Maximum days per sync

GARMIN_MCP_LOG_LEVEL

INFO

Log level

Set GARMIN_MCP_PUBLIC_URL when deploying remotely. MCP DNS-rebinding protection allows the hostname from this URL plus local development hosts.

Docker

Login once using a mounted data directory, then start the service:

docker compose run --rm garmin-open-mcp login
docker compose run --rm garmin-open-mcp sync --days 7
docker compose up -d

Development

uv sync --dev
uv run ruff check .
uv run ruff format --check .
uv run pytest

Tests use fake Garmin responses and never contact Garmin.

Troubleshooting

Login prints mobile+cffi returned 429

python-garminconnect tries several login strategies. Garmin may rate-limit one or more strategies by IP address while a later widget or portal strategy still succeeds. If the command ends with Connected: and garmin-open-mcp status --verify reports connected: true, the saved session is valid.

Do not repeatedly run login after success. Normal server requests load and refresh the saved token session instead of performing another password login. If every strategy is rate-limited and no token is saved, stop retrying and wait for Garmin's cooldown.

Security model

  • This is designed as a single-user service.

  • Do not publish your API key or commit the data directory.

  • Do not make a GPT containing your API key public.

  • Put the service behind HTTPS.

  • Back up the SQLite database only if you are comfortable storing a copy of health data.

  • Logout deletes Garmin session tokens but leaves cached health data. Delete the data directory to erase everything.

See SECURITY.md for reporting vulnerabilities.

License

MIT. See LICENSE.

Available Tools

11 tools
garmin_compare_periodsA
Read-onlyIdempotent

Compare daily averages for two locally cached date ranges.

Inputs: first_end (required), second_end (required), first_start (required), second_start (required). Returns: object

garmin_connection_statusA
Read-onlyIdempotent

Check whether a Garmin session exists and when data was last synchronized.

Inputs: verify. Returns: object

garmin_get_activityA
Read-onlyIdempotent

Get one activity. Samples are capped and omitted unless explicitly requested.

Inputs: activity_id (required), refresh, include_samples. Returns: object

garmin_get_body_metricsB
Read-onlyIdempotent

Get body composition and blood-pressure data for a date range.

Inputs: end_date (required), start_date (required), refresh. Returns: object

garmin_get_dayA
Read-onlyIdempotent

Get a consolidated health summary for one YYYY-MM-DD date.

Inputs: day (required), refresh. Returns: object

garmin_get_sleepA
Read-onlyIdempotent

Get sleep stages and available sleep metrics for one YYYY-MM-DD date.

Inputs: day (required), refresh, include_raw. Returns: object

garmin_get_training_statusA
Read-onlyIdempotent

Get Garmin training status and readiness for one YYYY-MM-DD date.

Inputs: day (required), refresh. Returns: object

garmin_list_activitiesA
Read-onlyIdempotent

List activities in an inclusive date range using YYYY-MM-DD dates.

Inputs: end_date (required), start_date (required), limit, refresh, +1 more. Returns: object

garmin_recent_overviewB
Read-onlyIdempotent

Return cached trends and activities for the most recent number of days.

Inputs: days. Returns: object

garmin_syncA
Read-onlyIdempotent

Synchronize recent Garmin daily summaries and activities into the local cache.

Use sparingly because Garmin's unofficial API can rate-limit frequent requests.

Inputs: days. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct resource or operation: connection status, sync, day summary, sleep, activities list/get, training status, body metrics, trends, period comparison, and recent overview. Even the cached-data tools are clearly separated by their analytical purpose.

    Naming Consistency5/5

    All tools follow a consistent garmin_ prefix with a verb_noun structure (check, sync, get, list). The naming pattern is uniform and predictable, making it easy to infer what each tool does.

    Tool Count5/5

    At 11 tools, the server is well-scoped for a health-data integration. It covers core data access, activity management, analytics, and connection handling without unnecessary bloat or gaps.

    Completeness4/5

    The surface covers major Garmin data domains: daily summary, sleep, activities, body metrics, training status, and cached data analysis. Minor gaps exist (e.g., no explicit hydration or intraday detail endpoints), but the core workflows are complete.

    Related MCP Connectors

    Related MCP Servers