Garmin MCP for macOS

A local MCP server for all 26 documented Garmin Connect Personal API GET endpoints, plus 8 convenient summary tools. Uses Garmin's official Python client and your own Personal API key. Independent community project; not affiliated with or endorsed by Garmin.

한국어 설치 안내 · All tools and API coverage · Security and privacy · Contributing

Requirements

• macOS with an unlocked login Keychain. Windows and Linux credential storage are not supported in this release.

• uv and Git. The installer provisions Python 3.12 through uv if needed.

• A Garmin account with a Personal API key. Each user creates and uses their own key.

• An MCP client that supports local STDIO servers, such as Codex.

Related MCP server: garmin-mcp

Install and connect

git clone https://github.com/devnjw/garmin-mcp.git
cd garmin-mcp
./scripts/install.sh
./scripts/run.sh auth
./scripts/run.sh check

auth asks for the key in a hidden Terminal prompt, verifies it with Garmin, then saves it in macOS Keychain. You can also open scripts/Garmin-API-Key.command in Terminal. Do not enter the key in chat, source files, shell arguments or MCP configuration. A macOS Keychain prompt may request permission for the installed Python executable.

check verifies authentication and checks today's summary plus the last seven days of sleep, HRV, Body Battery and activities. It prints statuses and counts, not health measurements or credentials. partial and no_data describe missing records; error means a request failed. This command does not exercise every API endpoint.

From the cloned repository directory, register with Codex:

codex mcp add garmin -- "$(pwd)/scripts/run.sh"

In Codex Settings → MCP servers, restart garmin, then use a new chat. For other STDIO clients, use the absolute path to scripts/run.sh as the server command. Keep the cloned directory in place. See official Codex MCP configuration.

Optional Codex settings in ~/.codex/config.toml:

[mcp_servers.garmin]
command = "/absolute/path/to/garmin-mcp/scripts/run.sh"
tool_timeout_sec = 180

[mcp_servers.garmin.env]
GARMIN_MCP_TIMEZONE = "Europe/Berlin"

Choose your own IANA timezone. Without this setting, the server reads the Mac's configured zone through /etc/localtime, falling back to UTC if unavailable. Garmin's calendar dates are preserved; summary timestamps are displayed in the selected timezone.

Try: “Show my sleep, HRV and workouts for the last seven days, including missing dates.”

What is supported?

Summary tools: garmin_status, garmin_daily_summary, garmin_sleep, garmin_hrv, garmin_body_battery, garmin_activities, garmin_activity, garmin_day.

Full API tools: 26 garmin_api_* tools expose all operations and documented parameters in the official Personal API 1.0.0 Swagger snapshot checked on 2026-10-24. This includes every documented activity-search filter, original JSON fields, profile, food logs, menstrual health, heart-rate zones, weight endpoints and original activity ZIP downloads. Complete mapping and limits.

• Summary ranges default to seven days and allow 90 days, split into 31-day requests.

• Raw range tools default to seven days and allow 31 days per call. Query consecutive intervals for longer history; raw responses are not merged or silently truncated.

• Raw activity search allows 1–100 records per page and all documented filters, with next_start. Its date filters can span longer history.

• Raw JSON preserves Garmin field names, units, nulls, negative sentinels and placeholders. Use summary tools for normalized metrics and explicit missing dates.

• garmin_api_download_activity creates a new private ZIP file, never extracts or overwrites files, and returns its path/size/hash. Files can contain GPS tracks.

• garmin_api_heart_rate_zones defaults generate_defaults to false. Explicitly enabling it may generate zone settings in Garmin. This tool and the local download tool are marked as potentially writing; the other 32 tools are marked read-only.

API coverage does not imply that every Garmin app feature is available, every device records every metric, or every account has data for every endpoint. There are no workout-upload or record-editing endpoints in this API snapshot. Empty data and denied access remain distinguishable.

Known live-API limitation: weight/all returned HTTP 400 during verification even with documented ISO dates. Its tool preserves the error and suggests garmin_api_weight_range(include_all=true), which succeeded. It does not silently change endpoints or response shapes. Verification details.

Privacy and storage

Data returned through MCP is available to your AI client/model and may be retained by that client. Raw tools can return account identifiers, precise location and sensitive health information. There is no telemetry or hosted relay in this project. Only the documented Garmin HTTPS host is contacted during use; uv contacts package sources during installation.

Garmin describes the Personal API as access to an individual's own data, not a commercial multi-user service. Distributing this client does not change those API terms. See Garmin's FAQ.

Update and troubleshoot

git pull --ff-only
./scripts/install.sh
./scripts/run.sh check

Restart the MCP server after updating. Re-running the installer preserves the Keychain entry. A key that expires or is revoked requires ./scripts/run.sh auth again.

• keychain_locked: unlock the login Keychain or allow the local Python executable access.

• authentication_failed: create a fresh Personal API key and run auth.

• access_denied: Garmin declined access; this is not an empty measurement.

• rate_limited: wait before retrying. The server does not loop on 429 responses.

• response_too_large: use a smaller range or page. JSON responses are limited to 8 MiB; activity ZIPs to 64 MiB.

• schema_changed: report the affected tool and sanitized structural details. Do not attach a real API response containing private data.

To uninstall, remove the MCP server entry, delete the clone and ~/.local/share/garmin-mcp, and delete the garmin-mcp item in Keychain Access. Revoke the key in Garmin Connect if no longer needed.

Development and verification

uv sync --frozen --python 3.12
uv run --frozen pytest -q
uv run --frozen ruff check .
uv run --frozen ruff format --check .
uv build

Tests use synthetic data and block network requests. CI checks supported Python versions on macOS, including the MCP protocol, all endpoint/parameter mappings, credential handling, downloads and summary regressions. See verification scope. CI never requires a Garmin key.

License

Apache-2.0. Garmin's official garmin-connect-personal-api-python dependency is also Apache-2.0. See third-party notices.