<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

```bash
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:

```bash
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:

```bash
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

```text
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:

```json
{
  "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.