health-os MCP server

health-os

Local-first personal health record, exposed over MCP. 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.

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

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.

• Lab results — drop a PDF or photo into your MCP client; the model extracts the values,

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.

• Safety net in code — critical values alert immediately (log, macOS notification,

age-gated risk calculators, a screening calendar, a weekly report, a doctor-visit brief.

• Trends and analytics — Mann-Kendall trends, personal baselines and anomalies,

see mcp_server/README.md.

• Food log — meals with a 41-nutrient profile, %RDA, deficiency/excess flags, meal templates.
• Devices — Apple Health export and Garmin import.
• 28 MCP tools + server instructions — the safety rules are sent to every client on connect;

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:

git clone https://github.com/andronaft/health-os && cd health-os/demo
docker compose up -d --build

Point your MCP client at it:

{
  "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",
               "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 docker compose down -v.

Install for your own data

Requires Docker and Python 3.12+.

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 mcpserver/README.md. Try: "show my health summary", "LDL trend", "what am I short on nutritionally this week?"*.

Shortened. The full README is on GitHub.