Garmin Open MCP

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

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.