# Renpho Health MCP

![License: MIT](https://img.shields.io/badge/license-MIT-blue)
![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
![Interface: CLI + MCP](https://img.shields.io/badge/interface-CLI%20%2B%20MCP-8A2BE2)

Own your Renpho smart-scale data — pull it out of the Renpho app into a raw time series log on your machine, and explore it conversationally from an AI agent.

Renpho scales only expose their readings through the Renpho mobile app — no export, no official API. This project logs in with your Renpho account, pulls every reading (weight, body fat %, muscle, water, BMI, and the rest), and keeps them as an append-only log you control. It also ships an **MCP server** so Claude Code (or any MCP-capable agent) can answer questions about your history — *"what's my weight trend this year?"*, *"lowest body fat ever?"* — by querying that log.

## Demo

Exploring the data from Claude Code via the MCP server:

![renpho-health MCP demo](assets/renpho-health-mcp-demo.gif)

▶ [Watch the full video](assets/renpho-health-mcp-demo.mp4) for higher quality.

## How it works

1. You provide your **Renpho account credentials** in a local `.env`.
2. A sync **authenticates** with Renpho and **pulls your full reading history** — the API has no date filter, so every sync fetches everything.
3. Readings are **deduplicated by timestamp** and **appended** to a raw JSONL log (the source of truth); a spreadsheet-friendly CSV is regenerated alongside it.
4. You explore the log **directly** (it's plain files) or **via the MCP server**, which exposes query/trend tools to an AI agent. The server does the math and returns data; the agent reasons over it.

Nothing leaves your machine except the calls to Renpho's own servers. There is no LLM inside this project — the "intelligence" is whatever agent you connect to the MCP server.

## Quick start

```bash
pip install -e ".[dev]"          # install
cp .env.example .env             # then add your Renpho email + password
renpho-sync                      # pull your history into data/renpho_log.jsonl
```

Then register the MCP server (see [Usage](#explore-your-data-with-an-ai-agent-mcp)) to explore it from an AI agent.

## Usage

### Sync your data

Run a sync whenever you want to capture new weigh-ins:

```bash
renpho-sync                      # one-shot, no server (also: python -m renpho_health.cli)
```

It's safe to run repeatedly — readings are deduplicated by timestamp, so re-runs never create duplicates:

```json
{ "pulled": 68, "new": 2, "skipped": 66, "total": 68 }
```

Two files are written (paths configurable — see Configuration):

- `data/renpho_log.jsonl` — the raw, append-only source of truth, one reading per line with every field the scale returned.
- `data/renpho_log.csv` — a spreadsheet-friendly view, regenerated from the JSONL on every sync.

There's also an HTTP trigger if you prefer a running service — `POST /sync` (plus `GET /health`):

```bash
uvicorn renpho_health.main:app --reload
curl -X POST http://127.0.0.1:8000/sync
```

### Explore your data with an AI agent (MCP)

The MCP server lets an AI agent query your readings. It reads the last-synced log offline; the `refresh` tool pulls new readings on demand.

Register it in Claude Code (requires the `claude` CLI — `npm install -g @anthropic-ai/claude-code`). This registers it at **user scope** so it's available in every session, with absolute paths baked in so it works from any folder:

```bash
claude mcp add -s user renpho \
  -e RENPHO_LOG_PATH=/absolute/path/to/data/renpho_log.jsonl \
  -e RENPHO_CSV_PATH=/absolute/path/to/data/renpho_log.csv \
  -- /absolute/path/to/.venv/Scripts/renpho-mcp
```

Use absolute paths (the launcher is `renpho-mcp.exe` on Windows). Equivalently, the launch command can be `python -m renpho_health.mcp_server` using the venv's Python.

Start a new session, confirm with `/mcp` (or `claude mcp list`), then ask e.g. *"using renpho, what's my current weight and how far am I down this year?"* The server exposes these tools plus a `renpho://readings` resource:

| Tool | Answers |
| --- | --- |
| `list_metrics` | What metrics exist, their units, and the date range covered |
| `latest` | Your most recent reading, all metrics |
| `history` | Readings over an ISO date range, or one metric's series |
| `stats` | min/max/mean/first/last/change for a metric over a range |
| `trend` | Direction and per-week rate of change |
| `refresh` | Pull new readings from Renpho into the local log |

Notes:
- **Dates are ISO 8601 (`YYYY-MM-DD`) only**, so there's no `DD-MM`/`MM-DD` ambiguity — the agent resolves "last 3 months" to a real date before calling.
- **Units** are reported per metric from a curated map (values are stored canonically, e.g. weight in kg); metrics whose unit isn't certain report `null` rather than guess.
- The read-only tools work from anywhere; **`refresh`** additionally needs `RENPHO_EMAIL`/`RENPHO_PASSWORD` — either run from the project folder (so `.env` loads) or add them as `-e` vars when registering. See [docs/adr/0004-mcp-server.md](docs/adr/0004-mcp-server.md).

## Configuration

Copy [.env.example](.env.example) to `.env` and fill in your Renpho account:

| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `RENPHO_EMAIL` | for sync/refresh | — | Your Renpho account email |
| `RENPHO_PASSWORD` | for sync/refresh | — | Your Renpho account password |
| `RENPHO_LOG_PATH` | no | `data/renpho_log.jsonl` | Raw JSONL log path |
| `RENPHO_CSV_PATH` | no | `data/renpho_log.csv` | Derived CSV path |

Your credentials and the `data/` directory (personal health data) are gitignored and never leave your machine. Renpho has no official API; this talks to Renpho's app backend using a reverse-engineered protocol (see [docs/adr/0002-own-renpho-client.md](docs/adr/0002-own-renpho-client.md)).

## Architecture

A pull pipeline feeds a local log that two front ends read from: an HTTP endpoint / CLI for syncing, and an MCP server for querying. All the analytics live in a pure, testable module; the MCP server and HTTP app are thin wrappers over it.

```
src/renpho_health/
  renpho/        # in-repo Renpho API client (AES-128-ECB envelope)
  store.py       # append-only JSONL log + derived CSV, dedup by timeStamp
  sync.py        # pull -> dedup -> log pipeline (run_sync)
  cli.py         # `renpho-sync` command
  main.py        # FastAPI app: POST /sync, GET /health
  queries.py     # pure analytics over the log (stats, trend, history)
  mcp_server.py  # MCP server: tools + renpho://readings resource
tests/           # pytest suite (no network — fakes the Renpho client)
docs/            # specs, ADRs, devlog
```

## Roadmap

- Sync the log into a destination of your choosing — a Google Doc or a Markdown file in a Google Drive vault ([spec](docs/specs/2026-07-22-renpho-data-sync.md)).
- An automatic scheduler so syncs run without manual triggering.

## Changelog & development notes

See [CHANGELOG.md](CHANGELOG.md) for release history, [docs/DEVLOG.md](docs/DEVLOG.md) for development history, [docs/adr/](docs/adr/) for design decisions, and [docs/specs/](docs/specs/) for feature specs.

## License

MIT — see [LICENSE](LICENSE).