health-mcp

<div align="center"> <img src="icon.png" alt="health-mcp logo" width="140"> <h1>health-mcp</h1> <p>An MCP server that exposes personal Garmin wellness data.</p> </div>

Setup

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

export GARMIN_EMAIL="you@example.com"
export GARMIN_PASSWORD="your-password"
export GARMIN_TOKEN_STORE="$HOME/.config/health-mcp/garmin-tokens"
export GARMIN_CACHE_TTL_SECONDS="300"
python server.py

The same variables are listed in .env.example. Copy it to .env and replace the example values. The server loads .env from the project directory.

GARMIN_TOKEN_STORE is optional and defaults to the path shown above. Login tokens are reused so the account credentials are not submitted on every call.

Garmin responses are cached in memory for five minutes by default. Set GARMIN_CACHE_TTL_SECONDS to change the duration, or set it to 0 to disable caching. The cache is shared across tools and resets when the server restarts. Failed Garmin requests are never cached.

If Garmin requests MFA on the first login, set GARMIN_MFA_CODE to the current code and restart the server. Remove it after tokens have been created.

For Garmin China accounts, set GARMIN_IS_CN=true.

Running

For an MCP client that launches the server as a subprocess:

python server.py

This uses stdio. Do not type tool names into that terminal because standard input carries MCP JSON-RPC messages.

To expose a local Streamable HTTP MCP endpoint:

python server.py --transport http

The endpoint is http://127.0.0.1:8000/mcp. It is an MCP endpoint rather than a REST endpoint, so connect with an MCP client. Use --host and --port to change the binding.

Project structure

server.py                  # Thin command-line entry point
gateway.py                 # Garmin Connect integration
mcp/
├── main.py                # Server construction and transport startup
├── models.py              # MCP response models
└── tools.py               # MCP tool registration and handlers
tests/                     # Unit tests

The local mcp/ directory intentionally has no __init__.py. FastMCP depends on a third-party Python package also named mcp, so making this directory a package would shadow that dependency.

Tools

• get_summary
• get_sleep
• get_hrv
• get_heart_rate
• get_stress
• get_body_battery
• get_history

All tools accept ISO dates (YYYY-MM-DD) and default to the current local date. The Body Battery tool accepts an optional date range.

get_history accepts an inclusive start_date, optional end_date, and an optional list of metrics:

{
  "start_date": "2026-06-01",
  "end_date": "2026-06-07",
  "metrics": ["sleep", "hrv", "heart_rate"]
}

History requests are limited to 31 days. Body Battery is fetched with Garmin's range endpoint. Summary, sleep, HRV, heart rate, and stress use Garmin's daily endpoints in date order. Successful dates are returned even when another date fails; failures appear in the response's errors list. Cached daily responses are reused across overlapping history requests.

This project uses Garmin Connect's unofficial API. Garmin may change its endpoints or response fields without notice.