garmin-mcp

An MCP server over one person's Garmin Connect account — reads, plus structured workout creation and calendar scheduling.

Status: pass 2, phase 4a. One tool (garmin_auth_status) plus a local web UI for signing in and checking the machine's state. The data and workout tools come next.

Read docs/SCOPE.md before adding to it.

Use it

Pull the image. It is built for linux/amd64 and linux/arm64, so it runs natively on both Intel and Apple Silicon:

docker pull ghcr.io/navyasree-anumula/garmin-mcp:latest

If the GHCR package is private you will need to authenticate once first (docker login ghcr.io with a personal access token carrying read:packages). If it is public, the pull needs no authentication at all.

To build it yourself instead:

docker build -t ghcr.io/navyasree-anumula/garmin-mcp:latest .

Bootstrap once. This is the only place a password is ever entered — -it because getpass needs a TTY:

docker run -it --rm -v garmin-tokens:/data ghcr.io/navyasree-anumula/garmin-mcp:latest login

Then back up the token volume immediately. If a captcha ever blocks a fresh login, this file is the only way back:

docker run --rm -v garmin-tokens:/data -v "$PWD":/backup alpine \
  cp /data/garmin_tokens.json /backup/

The web UI

Two pages — a status page and a sign-in form — served on demand and stopped when you are done. It never runs on its own, and nothing starts it for you:

docker compose up -d web     # then open http://127.0.0.1:8765/
docker compose down

The status page answers "is this machine set up": whether tokens exist, when they were written, whether their permissions are still 0600, whether the volume supports flock, and which build is running. It makes no call to Garmin, so it costs nothing to reload and cannot itself get you rate limited. It never shows what the tokens contain.

The sign-in form is the same exchange as login, in a browser. It is a deliberate security regression against getpass — a browser means password managers, autofill, extensions and devtools can all see the field, where a terminal exposed none of them. The CLI stays available for anyone who wants the tighter boundary, and it is the only route that can handle an MFA code.

Add it to Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "garmin": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "garmin-tokens:/data",
                "ghcr.io/navyasree-anumula/garmin-mcp:latest", "serve"]
    }
  }
}

Related MCP server: Garmin Cache MCP Server

Things that are easy to get wrong

• -it for login, -i alone for serve. A TTY applies line-discipline translation and corrupts the JSON-RPC stream. Same image, two invocations, and mixing them up gives a confusing protocol failure rather than a clean error.

• The password goes through the CLI, never an MCP tool. The serving container holds tokens only and cannot log in. That is deliberate, and it is what keeps a live credential out of conversation transcripts.

• Never print() in this server. stdout carries the protocol. All logging goes to stderr; tests/test_stdio_purity.py enforces it.

• A configured server appears under Settings → Connectors, not Settings → Developer. The Developer page has a "Local MCP servers" list that stays on "No servers added" even while a config-file server is connected and answering. Look in Connectors, where it shows as Desktop / Local dev / Connected. An hour was lost to reading the Developer page and concluding the config had been ignored.

• If it does not appear, redo the restart before anything else. Quitting from the tray icon is the documented step and it is easy to believe it happened when it did not — closing the window is not enough. Ten seconds, and it beats every other diagnostic here.

• The web UI's loopback guarantee is in the publish spec, not the bind address. Inside the container it binds 0.0.0.0 — it has to, because a process bound to 127.0.0.1 in a container's own network namespace is unreachable through a published port. What keeps it local is 127.0.0.1:8765:8765 in docker-compose.yml, backed by a Host header allowlist that rejects anything else. Run outside a container, the web command defaults to 127.0.0.1, so typing nothing gets you the safe case.

• Loopback is not the same as safe. The threat is the browser already running on your machine: any page you visit can reach 127.0.0.1, and DNS rebinding defeats a naive origin check. Hence the Host allowlist, same-origin enforcement, a per-form CSRF token, and no CORS headers anywhere. tests/test_web_security.py covers each one, and each was observed to fail with its guard removed.

• The HTTP transport must be published to loopback only. serve --http binds 0.0.0.0 inside the container on purpose — exposure is controlled by Docker: -p 127.0.0.1:3001:3001 is correct, -p 3001:3001 serves your health data to every network the machine joins, with no authentication.

• Deletes are permanently excluded from the tool surface.

• The dependency is pinned floor-and-ceiling (>=0.3.11,<0.4), never exactly — an exact pin is what stranded the most popular existing server on a stale release.

Claude chat / mobile

They cannot reach this. Claude connects to remote MCP servers from Anthropic's cloud, not from your device, so a server on your laptop is unreachable no matter how it is configured. Reaching it from chat needs a public HTTPS tunnel and authentication in front of it — Claude permits authless remote servers, so the lazy version of that is a public, unauthenticated endpoint serving your health data. That work gets its own plan.

Develop

python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest tests/ -q

CI

.github/workflows/docker.yml runs the tests, then builds and publishes the multi-arch image to GHCR. Pull requests build the image but cannot publish it — the registry login step is skipped for them, so a PR proves the build without being able to ship one.

Tags: latest on main, a short-SHA tag on every push, and a semver tag when a v* tag is pushed.