MCP Server for garth-ng

A thin MCP server layer over the garth-ng library, exposing your own Garmin Connect data to an LLM via the Model Context Protocol — plus a small local store for body measurements Garmin cannot hold (see Body Measurements).

Disclaimer: This is an unofficial, personal project, not affiliated with or endorsed by Garmin. It uses garth-ng, which talks to undocumented, reverse-engineered Garmin Connect endpoints. Use at your own risk, with your own account and credentials.

Project Structure

mcp-garmin/
├── src/
│   ├── config.py            # Central config: env vars, credentials checked on demand
│   ├── server_instance.py  # Creates the shared MCPServer instance
│   ├── mcp_server.py       # Composition root: wires up the server + tools
│   ├── tools/               # One module per MCP tool
│   │   ├── _shared.py        # local_iso: normalizes garth's inconsistent timestamp types
│   │   ├── ping.py
│   │   ├── sleep.py
│   │   ├── hrv.py
│   │   ├── activity.py
│   │   ├── strength.py
│   │   ├── steps.py
│   │   ├── calories.py
│   │   ├── weight.py
│   │   ├── training_readiness.py
│   │   ├── metrics.py         # The five measurement tools over metrics_store.py
│   │   └── daily_review.py   # Morning check-in in one call: sleep, HRV, readiness, training
│   ├── metrics_store.py    # Local SQLite store for self-defined measurements (no Garmin access)
│   ├── garmin_client.py    # Garth login/session handling + data access
│   ├── main.py              # Entry point (starts the server over stdio)
│   └── explore_sleep.py     # Standalone script for manually testing the Garth integration
├── tests/                    # Mirrors src/, mocks the garth boundary
│   ├── test_garmin_client.py
│   ├── test_config.py
│   ├── test_main.py
│   └── tools/
│       ├── test_ping.py
│       ├── test_sleep.py
│       ├── test_hrv.py
│       ├── test_activity.py
│       ├── test_strength.py
│       ├── test_steps.py
│       ├── test_calories.py
│       ├── test_weight.py
│       ├── test_training_readiness.py
│       ├── test_shared.py
│       └── test_daily_review.py
├── .github/
│   └── workflows/
│       └── ci.yml            # CI: pytest + ruff on 3.11 and 3.14
├── .env.template            # Template for credentials and settings
├── pyproject.toml           # ruff configuration: line length and rule set
├── pytest.ini
├── requirements.txt
├── requirements-dev.txt     # Adds pytest/pytest-cov/ruff on top of requirements.txt
├── LICENSE
└── README.md

Related MCP server: garmin-mcp-triathlon

Installation

Python 3.11 or newer is required (tested with 3.11 and 3.14; the CI checks both).

# Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Setting Up Credentials

cp .env.template .env

Fill in your Garmin Connect credentials in .env (GARMIN_USERNAME, GARMIN_PASSWORD, both required). On first run, this logs in once and saves the session under ~/.garth — after that, the saved session is reused without logging in again.

Two optional settings, with sensible defaults if omitted:

• LOG_LEVEL (default INFO) — one of DEBUG, INFO, WARNING, ERROR, CRITICAL

• GARTH_SESSION_DIR (default ~/.garth) — where the cached session is stored

Usage

Start the MCP server (waits over stdio for a client, e.g. Claude Desktop):

python src/main.py

For manually testing the Garth integration (without the MCP protocol):

python src/explore_sleep.py

For interactively testing the MCP server with the MCP Inspector:

npx -y @modelcontextprotocol/inspector ./venv/bin/mcp run src/mcp_server.py:server

Opens a browser tab with the Inspector UI, where the available tools can be called directly.

Known issue: mcp dev src/mcp_server.py:server (the CLI's own dev command) currently fails — it spins up an isolated uv run --with mcp==<version> environment that's missing the cli extras mcp run itself needs. The command above works around this by pointing the Inspector directly at this project's own virtual environment instead.

Running Tests

pip install -r requirements-dev.txt
pytest -v
pytest --cov=src --cov-report=term-missing  # with coverage
ruff check src tests                        # lint gate, must be clean

requirements-dev.txt adds pytest, pytest-cov and ruff on top of requirements.txt. The ruff rule set (line length 100, E, F, I, UP, B) lives in pyproject.toml, so the same command gives the same result in the editor and in CI. Tests mock the garth boundary (no real network calls or credentials needed) and live under tests/, mirroring the src/ structure.

Deployment (Hermes)

Install it with its own venv (see Installation above).

Hermes registration (mcp_servers in the profile's config.yaml):

mcp-garmin:
  command: /path/to/mcp-garmin/venv/bin/python
  args: [/path/to/mcp-garmin/src/main.py]
  env:
    GARMIN_USERNAME: ${GARMIN_USERNAME}
    GARMIN_PASSWORD: ${GARMIN_PASSWORD}
    GARTH_SESSION_DIR: ${GARTH_SESSION_DIR}   # e.g. ~/.garth

Body Measurements

Garmin Connect accepts a fixed body-composition schema (weight and friends), so everything else — waist, hip, a pulse taken by hand — has no place there. Those values live in a local SQLite store instead, next to the Garmin data in your training log:

• create_measurement_category(name, unit) — define a category once, e.g. waist / cm.

• list_measurement_categories() — what already exists, with the number of values and the newest timestamp.

• add_measurement(category, value, unit=None, measured_at=None) — record a value. The unit falls back to the category default; a different unit is stored as given. measured_at is local ISO 8601 (2026-10-18T06:35:00), a bare date means midnight, omitted means now. An unknown category is created on the fly when you pass a unit.

• get_measurements(category, start=None, end=None) — the series, ascending.

• get_measurement_summary(category, start=None, end=None) — per unit: count, first, last, delta, min, max and the ISO-week averages (2026-W42, Monday to Sunday).

A typical exchange:

You: My waist was 95 cm on 12 October and 96 cm on 14 October. Assistant: (calls add_measurement("waist", 95, "cm", "2026-10-12T07:00:00"), then the same for the 14th) You: How has my waist developed? Assistant: (calls get_measurement_summary("waist")) — one week so far, 2026-W42, average 95.5 cm from two measurements.

Rules worth knowing:

• Units are never converted. cm and in stay separate blocks — you get back exactly the numbers you entered.

• Weeks are ISO weeks (Monday–Sunday), labelled by the ISO week-year: 2025-12-29 belongs to 2026-W01.

• Nothing leaves the machine. These five tools never call Garmin Connect; they need no credentials and no network.

• The file is GARMIN_METRICS_DB, default ~/.garmin-metrics.db, created on first use (parent directory included).

• Errors name the offending value: an unparsable timestamp, NaN/inf, an empty category, a duplicate category with the unit that already exists, or an unusable database path.

get_weight_summary stays the source for everything the scale measures — the store is for what Garmin cannot hold.

Available Tools

| get_daily_review(target_date, days=6, language="en") | Morning check-in in ONE call: last night's sleep, HRV (vs. weekly average), training readiness with all factors, the latest weigh-in, the previous day's training with details and strength sets, steps, and the days before as context — pre-formatted text plus a ready-made status line for a training log. days is the training context before the reviewed day (0-13), language (en or de) sets weekday names and the status line |

All dates are ISO 8601 (YYYY-MM-DD).

Scope / Limitations

• A single-user tool, not a service: it runs locally over stdio — no network port, no authentication.

• It uses the unofficial Garmin Connect endpoints via garth-ng, which can break at any time (see the disclaimer above).

• Credentials are stored in plain text in .env; the .garth session directory and .env must not be committed.

• It handles personal health data. Keep the repository, logs and issue reports free of that data.

• The five measurement tools are the exception to "Garmin only": they never call Garmin Connect. They keep self-defined values (waist, hip, …) in a local SQLite file (GARMIN_METRICS_DB, default ~/.garmin-metrics.db), because Garmin's only write endpoint accepts a fixed body-composition schema. Values of different units are stored as given and never converted.

License

MIT