"How did I sleep last week? What's my training readiness today? Summarise my last 5 runs and tell me if I'm overtraining."

Ask your assistant — it now has the data.

✨ Highlights

• Full API coverage — 48 hand-crafted tools for the everyday questions (with friendly date handling) plus every remaining garminconnect method auto-exposed (100+ tools total), so the complete Garmin Connect surface is available: endurance score, intensity minutes, FTP, lactate threshold, nutrition, golf, gear stats, training plans, scheduled workouts, and all write/upload/delete actions.
• Token-based auth with MFA support — log in once, no password stored at runtime. Tokens are cached locally and auto-refreshed.
• Secure by default — credentials and OAuth tokens are .gitignored and can never be committed.
• LLM-friendly responses — huge time-series payloads are automatically trimmed so they fit comfortably in a model's context window.
• Resilient — transparent re-authentication on session expiry, friendly human-readable date inputs (today, yesterday, -7).
• Tested — a mocked, offline unit-test suite plus a live integration script you can point at your own account.

📊 What you can ask

🚀 Quick start

1. Install

git clone https://github.com/stitrace/garmin-mcp-server.git
cd garmin-mcp-server

# with uv (recommended)
uv venv && uv pip install -e .

# …or with pip
python -m venv .venv && source .venv/bin/activate
pip install -e .

2. Authenticate (one time)

Run the interactive login. It handles multi-factor authentication and caches OAuth tokens to ~/.garminconnect so the server never needs your password again.

garmin-mcp-server-login

Garmin Connect — interactive login
----------------------------------------
Email: you@example.com
Password: ********
MFA / 2FA code: 123456
----------------------------------------
Success! Logged in as: Jane Runner
Tokens cached to: /home/you/.garminconnect

🔐 Your password is used only for this one login and is never written to disk. From here on, authentication uses the cached tokens.

3. Run

garmin-mcp-server          # starts the MCP server over stdio

That's it. Now wire it into your favourite MCP client. 👇

🔌 Connect your client

Claude Desktop

Add to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "garmin": {
      "command": "garmin-mcp-server"
    }
  }
}

If garmin-mcp-server isn't on your PATH, use the absolute path to the executable in your virtual environment (e.g. /path/to/garmin-mcp-server/.venv/bin/garmin-mcp-server), or:

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

Claude Code

claude mcp add garmin -- garmin-mcp-server

Cursor / other MCP clients

Point the client at the garmin-mcp-server command (stdio transport). Any MCP-compliant client works the same way.

🧰 Tool reference

✍️ = tool writes to your Garmin account. Everything else is read-only.

Auto-exposed tools

Beyond the curated tools above, every other public garminconnect method is registered automatically using the library's native signature. This means the full API is available — for example get_endurance_score, get_intensity_minutes_data, get_weekly_steps, get_cycling_ftp, get_lactate_threshold, get_running_tolerance, get_nutrition_daily_food_log, get_gear_stats, get_training_plans, get_scheduled_workouts, the badge and golf endpoints, and write/upload/delete actions (upload_activity, set_blood_pressure, delete_activity, …).

These auto-exposed tools take the same arguments as the underlying garminconnect method. The list updates itself whenever you upgrade the library. Destructive actions (delete_*) are labelled in their tool descriptions — use with care.

Friendly date inputs

Every date argument accepts natural values — no need to compute calendar dates:

⚙️ Configuration

All configuration is via environment variables (a local .env file is supported and auto-loaded). See .env.example.

🔒 Security

Your health data is sensitive — this project treats it that way.

• No secrets in git. .env, *.env, token stores (oauth*_token.json, .garminconnect/, .garth/) and downloaded activity files are all .gitignored. Run git check-ignore .env to confirm.
• Password-optional runtime. After garmin-mcp-server-login, the server runs on cached tokens alone — no password is read or stored.
• Local only. Tokens live on your machine; nothing is sent anywhere except Garmin's own API.

⚠️ Never paste real credentials into issues, PRs, or commits. If you think a token leaked, revoke access in your Garmin account and delete the token cache.

🛠️ Development

uv pip install -e ".[dev]"

ruff check garmin_mcp_server tests     # lint
pytest                          # unit tests (mocked, no network)

The unit tests mock the Garmin client and run offline. There is also a manual live integration check — point GARMINTOKENS at a valid token cache and call the tools in garmin_mcp_server.server directly.

garmin_mcp_server/
├── server.py     # FastMCP app + all tool definitions
├── client.py     # lazy, resilient, thread-safe Garmin client wrapper
├── login.py      # one-time interactive login (handles MFA)
├── config.py     # environment configuration
└── helpers.py    # date parsing + response trimming

🚢 Releasing

Releases are automated by .github/workflows/release.yml. Pushing a version tag lints, tests, builds the wheel/sdist, publishes a GitHub Release with auto-generated notes, and publishes to PyPI via Trusted Publishing (OIDC — no API tokens are stored anywhere).

To cut a release:

1. Bump the version in both pyproject.toml and garmin_mcp_server/__init__.py (the workflow fails if the tag doesn't match the package version), and move the CHANGELOG.md entries under the new version.
2. Tag and push:

   git tag -a v0.1.1 -m "v0.1.1"
   git push origin v0.1.1
   

One-time PyPI setup (Trusted Publishing)

Before the first PyPI publish, register this repo as a trusted publisher — no secrets required. At https://pypi.org/manage/account/publishing/ add a pending publisher with:

Then create a GitHub Environment named pypi (repo Settings → Environments) to gate publishes. After that, every v* tag lands on PyPI and pip install garmin-mcp-server just works.

❓ Troubleshooting

🙏 Acknowledgements

• Built for cyclosport.app.
• python-garminconnect — the excellent library this server builds on (it now talks to Garmin directly; the formerly-used garth is no longer a dependency).
• Model Context Protocol by Anthropic.

📄 License

MIT © Andrey Chubarov