garmin-watch-mcp

An MCP server that gives Claude (or any MCP client) read-only access to the health and activity data your Garmin watch syncs to Garmin Connect: daily summaries, sleep, heart rate, stress, Body Battery, HRV, training readiness, activities and devices. It talks to Garmin Connect through python-garminconnect, wrapped in a small async client (garmin_watch_mcp.core).

Tools

Day-based tools take an optional date (YYYY-MM-DD, today or yesterday), which defaults to today in the server's local time zone. Durations are seconds, distances metres and speeds m/s. Garmin's raw responses are large, so each tool keeps a curated set of fields and summarises intraday samples by hour (UTC).

Related MCP server: garmin-mcp

Setup

For a step-by-step guide, including MFA and troubleshooting, see the installation guide. Full documentation is at https://garmin-watch-mcp.readthedocs.io.

You need a Garmin Connect account that your watch syncs to.

git clone https://github.com/osjayaprakash/garmin-watch-mcp.git && cd garmin-watch-mcp
uv sync
uv run garmin-watch-mcp login   # once: asks for email, password and MFA code, saves tokens

login saves OAuth tokens to ~/.garminconnect; the server reuses and refreshes them, so it needs no password afterwards. Without MFA you can skip login and set GARMIN_EMAIL/GARMIN_PASSWORD instead.

Run from PyPI

No clone needed; uv fetches and runs the published package:

uvx garmin-watch-mcp login   # once
uvx garmin-watch-mcp

In a client config, use "command": "uvx", "args": ["garmin-watch-mcp"].

Run with Docker

The server speaks MCP over stdio, so keep -i. Pass the tokens from garmin-watch-mcp login --print-tokens as GARMINTOKENS:

docker run -i --rm -e GARMINTOKENS ghcr.io/osjayaprakash/garmin-watch-mcp:latest

Or mount a token directory: -v ~/.garminconnect:/home/app/.garminconnect. In a client config, use "command": "docker" with those arguments, and pass the variables through the client's env block.

Claude Desktop

Add to claude_desktop_config.json:

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

Add an env block with GARMIN_EMAIL/GARMIN_PASSWORD if you didn't run login.

Claude Code

claude mcp add garmin -- uv --directory /absolute/path/to/garmin-watch-mcp run garmin-watch-mcp

Langfuse tracing (optional)

Each tool call becomes a Langfuse trace, with a child span for the Garmin Connect call. Install the extra and set the keys:

uv sync --extra langfuse

In the server command, use run --extra langfuse garmin-watch-mcp instead of run garmin-watch-mcp.

Privacy: sleep, heart rate and activity data are health data. By default, traces hold only tool names, timings and error class names. Setting LANGFUSE_CAPTURE_DATA=true sends the data itself to your Langfuse instance; only do that with an instance you trust, such as a self-hosted one.

Development

uv sync
uv run pytest            # offline suite
uv run pytest -m live    # hits the real API; needs saved tokens or GARMIN_EMAIL/PASSWORD
uv run ruff check src tests && uv run ruff format --check src tests

Releasing

Bump version in pyproject.toml and server.json, then push a matching tag (git tag v0.1.0 && git push --tags). That publishes:

License

MIT

Not affiliated with or endorsed by Garmin. Garmin Connect has no public personal-data API; this uses the same unofficial endpoints as the Garmin Connect app and may break when Garmin changes them.