health-os
# health-os
[](https://github.com/andronaft/health-os/actions/workflows/tests.yml)
[](https://mcpservers.org/servers/andronaft/health-os)
**Local-first personal health record, exposed over [MCP](https://modelcontextprotocol.io).**
Your labs, diagnoses, medications, wearable data and food log live in your own Postgres; any
MCP client — one running a local model or a cloud assistant — can read and update them through
guarded tools. Critical values, drug-safety rules and screening
schedules are deterministic code, not LLM judgement.
<p align="center"><img src="docs/demo.svg" alt="An MCP session with the demo patient: LDL trend and the pending-review queue" width="820"></p>
> **Medical disclaimer.** This is not a medical device and does not give medical advice.
> Critical-value alerts and screening reminders are only a signal to contact a doctor —
> never a diagnosis and never a reason to delay care. Use at your own risk.
## What it does
- **Lab results** — drop a PDF or photo into your MCP client; the model extracts the values,
health-os normalizes names (uk/ru/en/Latin synonyms) and units, and stages the panel as
*pending*. Nothing counts as fact until you approve it.
- **Safety net in code** — critical values alert immediately (log, macOS notification,
optional Telegram); critical findings in narrative reports are flagged; drug-interaction
questions are refused and redirected to a doctor/pharmacist (only deterministic checks run:
total daily paracetamol across products, biotin before lab tests); a crisis tool returns a
fixed response with hotlines, independent of the model.
- **Trends and analytics** — Mann-Kendall trends with a per-year slope, anomalies against your
own baseline (`get_anomalies`), a screening calendar, a weekly report, a doctor-visit brief.
Risk calculators (SCORE2, ASCVD, FRAX) so far only enforce their validated age range; the
formulas aren't implemented yet.
- **Food log** — meals with a 41-nutrient profile, %RDA, deficiency/excess flags, meal templates.
- **Devices** — Apple Health export and Garmin import.
- **38 MCP tools + server instructions** — the safety rules are sent to every client on connect;
see [mcp_server/README.md](mcp_server/README.md).
## Try it in one command
Only Docker needed. Starts a throwaway database with a fictional patient — two years of labs
(LDL creeping up), blood pressure, medications, a food log and a lab panel awaiting approval:
```bash
git clone https://github.com/andronaft/health-os && cd health-os
make demo # or: cd demo && docker compose up -d --build
```
Point your MCP client at it:
```json
{
"mcpServers": {
"health-os-demo": {
"command": "docker",
"args": ["run", "-i", "--rm", "--network", "health-os-demo",
"-e", "DATABASE_URL=postgresql+psycopg://health:demo@db:5432/health_os",
"-e", "READONLY_DATABASE_URL=postgresql+psycopg://health_readonly:demo_ro@db:5432/health_os",
"health-os:local"]
}
}
}
```
Ask *"show my health summary"*, *"is my LDL trending up?"*, *"what's pending review?"*,
*"what am I short on nutritionally?"*. Remove it all with `make demo-down`.
## Install for your own data
Requires Docker and Python 3.12+.
```bash
git clone https://github.com/andronaft/health-os && cd health-os
cp .env.example .env # set the passwords
docker compose up -d db # Postgres 16 + pgvector
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/alembic upgrade head # schema
.venv/bin/python -m seed.load # marker catalog, synonyms, units, nutrients
.venv/bin/python -m seed.demo # optional: a fictional demo patient to play with
```
Then connect an MCP client — config for LM Studio, Open WebUI, Ollama CLI and Claude is in
[mcp_server/README.md](mcp_server/README.md). Try: *"show my health summary"*,
*"LDL trend"*, *"what am I short on nutritionally this week?"*.
**Local models:** the server speaks standard MCP over stdio, so any MCP client that runs a
local model can use it. Verified so far: the server itself with the official MCP Python client
(CI + the Docker demo). Not yet verified end-to-end with a local model — see
[#9](https://github.com/andronaft/health-os/issues/9); reports welcome.
### Browser UI (preview)
```bash
make ui # or: .venv/bin/python -m web [--port N] [--no-browser]
```
Starts a local, read-only web page on `127.0.0.1:8765` (port: `UI_PORT` in `.env`) and opens it
with this run's session link. Only this machine can reach it: the server listens on 127.0.0.1,
refuses requests with a foreign `Host`, and its API answers only GET requests that carry the
session token. The Overview page shows your profile, what needs attention (critical values with
their escalation text, values awaiting review, latest values out of range, overdue screenings,
markers not checked in a long time), 30-day tiles for blood pressure, resting heart rate, HRV,
sleep score and weight, and recent events. It reads the same rows as `get_health_summary`, and
only ever says "N of M recorded markers in range". The other pages are still empty — they come in
0.4.0 ([milestone](https://github.com/andronaft/health-os/milestone/1)). Nothing is loaded from
outside this machine: Apache ECharts is kept in `web/static/vendor/` with its licence.
## How it works
<p align="center">
<img src="docs/architecture.drawio.svg" alt="Architecture: MCP client over stdio to mcp_server; read tools query approved views, write tools go through core/services into pending; safety, analytics, PostgreSQL with pgvector, ingestion" width="820">
</p>
### A lab result, from report to fact
Every row of a staged panel ends up **pending** — nothing becomes a fact without an explicit
approve. A row the catalog can't place is kept, not dropped:
<p align="center">
<img src="docs/lab-result-flow.drawio.svg" alt="How a lab result row moves from stage_lab_panel through pending states to approved" width="820">
</p>
Unmapped and pending rows show up in `list_pending_reviews` and in the health summary's
"awaiting review" block; a learned name maps automatically on the next panel.
| Directory | What's inside |
|---|---|
| `core/` | config, DB, normalization, services, dedup, health summary |
| `mcp_server/` | MCP server, read and write tools |
| `safety/` | deterministic safety rules and alert delivery |
| `analytics/` | trends, baselines, calculators, screening, nutrition, reports |
| `ingestion/` | extraction schema, confidence scoring, device importers, embeddings |
| `migrations/` | Alembic schema |
| `seed/` | reference catalog + the demo patient |
| `evals/` | red-team scenarios (injections, hidden critical values, unit tricks) |
| `scripts/` | backup/restore (restic; `install_launchd.sh` schedules them on macOS), read-only role setup, importers |
## Privacy / local-first
- **Your data stays in your own database.** Postgres runs locally in Docker; `data/` and `.env`
are outside git. Nothing is sent anywhere by health-os itself.
- **What leaves the machine depends on the MCP client you connect.** With a local model
(LM Studio, Open WebUI + Ollama, …) nothing does. With a cloud assistant, whatever the tools
return is sent to that provider — use one whose terms fit medical data (no training on your
data, zero/short retention).
- **The goal is fully local:** local models for chat and extraction, local embeddings for search
(already supported via fastembed). Cloud clients remain optional.
- Optional alert channel (Telegram) sends only a generic "check your health system" text, never values.
- Encrypt the disk (FileVault / LUKS / BitLocker) — the database files are plaintext at rest.
- Never put real medical data in issues, PRs or tests — synthetic data only.
## Tests
```bash
make test # everything (needs Postgres for the integration part)
make test-unit # pure unit tests — no database needed
make test-integration # only tests marked `integration`
```
Integration tests never touch the working database: `tests/conftest.py` drops and recreates
`<POSTGRES_DB>_test` on the same server (migrations + seed) on every run. Override with
`TEST_DATABASE_URL` (the name must end in `_test`). Without Postgres, integration tests are
skipped locally; CI sets `REQUIRE_DB=1` so they fail instead.
Development history: [PROGRESS.md](PROGRESS.md).
How the guardrails work: [How to let an LLM read your medical records without trusting it](https://zhukovskyi.space/blog/health-os-guardrails/). Made by [Andrii Zhukovskyi](https://zhukovskyi.space/).
## License
[AGPL-3.0-or-later](LICENSE). You may use, modify and fork health-os; if you distribute it or
run a modified version as a network service, you must publish your source under the same license.
Want to use it in a closed-source or commercial product without those obligations? A separate
commercial license is available from the author — reach out via GitHub
([@andronaft](https://github.com/andronaft)).
Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) (includes a short CLA).
TDQS
Scored across 36 tools
Most tools have clearly distinct clinical, nutritional, medication, lab, and habit scopes, and descriptions explicitly route between similar-looking tools such as query_food, query_nutrition, and nutrition_report. Some overlap remains among summary/report tools and the generic sql_query versus dedicated read tools, but an agent can usually select correctly.
The set overwhelmingly uses consistent snake_case names, mostly with recognizable verb_noun patterns such as get_medications, record_habit, update_meal, and approve_staged_source. Minor deviations include noun-first names like nutrition_report, sql_query, and crisis_resources, but the convention is still predictable.
With 36 tools, the set is large enough to impose significant selection overhead on an agent even for a broad health domain. Several read/report/summary tools could likely be consolidated or made more task-oriented without losing coverage.
Core workflows for meals, medications, habits, lab review, and reporting are well covered, but lifecycle gaps remain: allergies and diagnoses have create/read tools but no update/delete/correction tools. Visits, vaccinations, and hospitalizations appear in the timeline but have no obvious recording tools, which are notable omissions for a health OS.