health-mcp

Deine persönliche Gesundheitsdatenbank. Dein Agent übernimmt das Tippen.

Ein Local-First-Server, der deine Ernährungs-, Biomarker- und Wearable-Daten speichert. Das Ganze ist als Model Context Protocol-Tools bereitgestellt, sodass jeder MCP-fähige Agent (Hermes, OpenClaw) lesend und schreibend darauf zugreifen kann. Ein Web-Dashboard läuft im selben Prozess mit, für die Fälle, in denen du die Daten lieber ansehen möchtest, statt mit deinem Agenten zu sprechen.

Alles läuft auf deinem Rechner. Eine SQLite-Datei. Keine Konten, kein SaaS, keine Telemetrie.

Statt eine weitere Foto-CV-Kalorien-App oder einen Freitext-Parser zu bauen, überlässt du dem Agenten die unscharfen Teile („Ich hatte zwei Eier und Toast", „Logge dieses Labor-PDF", „Was beeinflusst meinen Schlaf-Score?") und diesem Server die dauerhaften Teile: typisiertes Schema, atomare Transaktionen, Bereichsabfragen, eine an Fähigkeiten gekoppelte Tool-Oberfläche und eine UI, die die darunterliegenden Daten nicht beschönigt.

Was es erfasst

Ernährung. Lebensmittel (USDA, Open Food Facts, manuelle Einträge), Mahlzeiten aus Lebensmittel / Rezeptportion / Batch / benutzerdefinierten Komponenten, Flüssigkeit, Gewicht, Körpermaße, Makrozle als {min, max}-Grenzen sowie Tages- / Wochen-Zusammenfassungen.

Rezepte und gekochte Batches. Rezepte skalieren auf Makros pro Portion. Ein Batch ist eine gekochte Instanz, die sich aufbraucht, wenn du davon isst – mit atomaren Dekrementen in log_meal und Erstattungen beim Löschen.

Gemerke Mahlzeiten. Markiere dein übliches Frühstück einmal und log es in einem einzigen Tool-Aufruf. Es enthält entweder bereits aufgelöste Komponenten (deterministisch) oder kanonischen Freitext (der Agent schätzt bei jedem Anruf neu).

Biomarker und Laborwerte. Etwa 60 kuratierte Biomarker mit LOINC-Codes, Standardeinheiten und Referenz- und Optimumbereichen. Labor-Panels werden atomar mit all ihren Ergebnissen eingefügt. Eine dreistufige Berechswald entscheidet über den Status jedes Ergebnisses: per-result Labor-Snapshot → per-biomarker aktualisiert → kuratiertes Optimum. Einheitskonversion für die üblichen Doppeleinheiten (mg/dL ↔ mmol/L, ng/mL ↔ nmol/L, etc.). „Trend and „Letzte Messung pro Marker“-Abfragen.

Wearables. Whoop und Oura über OAuth2 heute. Jeder Anbieter-Spiegel behält den Raw-Payload (raw_json pro Zeile), sodass eine zukünfigte Migration jedem Feld zu einer normalisierten Spalte rauben kann, ganz ohne zu synchronization. Normalisierte Tabellen (wearable_sleep, wearable_activity, wearable_readiness, wearable_daily) dich zum Lesen über Anbieter hinweg, ohne dass du dich um den verbundeten Anbieter kümmern musst. Refresh-Tokens rotieren; parallele 401s können das Token nicht doppelt verbrauchen, weil der Auth-Speicher pro Anbieter mit einem Mutex geschützt ist.

Einblicke. correlate führt Pearson- oder Spearman-Berechnung über zwei beliebige Messwertreihen durch, nach Tag / Woche / Monat gebuckelt. Vorzeichenbehaftete Lag-Buckets verschieben eine Reihe in der Zeit. Forward-Fill trägt den letzten Wert durch Lücken, sodass spärliche Messdaten sauber mit täglichen Wearable-Scores korrelieren. Das Tool bleibt im Katalog des Agenten verborgen, bis genügend Daten für eine belastbare Korrelation.

Schnellstart

npx

Node.js ≥ 20, kein Klonen oder Build:

npx health-mcp            # http://127.0.0.1:7777, opens the dashboard
npx health-mcp --stdio    # headless MCP server over stdio

Die Daten liegen in ~/.health-mcp/ (einer SQLite-Datei). npx health-mcp --help listet alle Flags; npx health-mcp doctor führt eine Selbstprüfung aus.

Docker

git clone https://github.com/lukaisailovic/health-mcp.git
cd health-mcp
cp .env.example .env

# Put a strong token in .env (required to bind off-loopback)
openssl rand -hex 32

docker compose up -d
open http://127.0.0.1:7777

Die Daten bleiben im benannten Volume health-mcp-data erhalten. Wenn du die Dateien lieber auf der Ressource sehen möchtest, ersetze das Volume-Mapping in docker-compose.yml für ./.health-mcp-data:/data ein.

docker compose down stoppt deinen Container; die Daten überleben Neustarts.

Wer ein vorgebautes Image dem lokalen Build bevorzugt? Trage in docker-compose.yml das published Image ein und entferne dessen build:-Block:

image: ghcr.io/lukaisailovic/health-mcp:latest   # or pin :0.1.0 / :0.1

Jede Veröffentlichung schickt :X.Y.Z, :X.Y und :latest; :main verfolgt den neuesten Commit. Alle Images tragen eine Build-Provenance-Attestierung. Siehe Releasing.

Aus dem Quellcode

Node.js ≥ 20 und pnpm.

git clone https://github.com/lukaisailovic/health-mcp.git
cd health-mcp
pnpm install
pnpm build
pnpm start                      # http://127.0.0.1:7777, browser opens automatically

Freispielen Entwicklung mit Hot Reload für Dashboard, gemeinsame Typen und Server: Führe alle drei im Watch-Modus aus:

pnpm dev
# server on :7777, dashboard dev on :5173 (proxies /api/* to :7777)

Übergib --no-open, um den Browser geschlossen zu lassen, oder --no-dashboard, um als headlesserv als MCP-/REST-Server zu laufen.

Unterbefehle

pnpm start -- migrate                  # apply pending DB migrations and exit
pnpm start -- doctor                   # self-check (DB pragmas, file modes, token entropy)
pnpm start -- export /tmp/dump.jsonl   # JSONL dump; raw_json redacted unless --include-raw
pnpm start -- import-usda dump.json    # ingest a USDA FoodData Central bulk JSON

Einen MCP-Agenten verbinden

Hermes / OpenClaw (stdio)

Beide verwendenden die Standard-MCP-Konfiguration, daher ist die IBS-Einrichtung identisch: füge health-mcp zur mcpServers-Liste deines Agenten hinzu. Kein Klonen oder Build nötig; verweise auf das wiedergegebene Paket:

{
  "mcpServers": {
    "health": {
      "command": "npx",
      "args": ["-y", "health-mcp", "--stdio"]
    }
  }
}

Wo dieser Block liegt, hängt vom Agenten ab; schaue in die MCP-Einstellungen des Agenten für den Pfad.

Dann frag deinen Agenten:

• „Logeier und toast for breakfast” → log_meal

• „Wie entwickelt sich mein Fasten widmuck?" → biomarker_trend

• „Korreliert meine Proteinzufahme mit und Areola–Erholung am nächsten Tag?" → correlate mit lag_buckets: 1

Läuft er aus einem lokalen Checkout? Verwende nach pnpm build "command": "node" mit "args": ["/path/to/health-mcp/apps/server/dist/index.js", "--stdio"], oder umgangen den Build mit "args": ["--import", "tsx", "/path/to/health-mcp/apps/server/src/index.ts", "--stdio"].

MCP Inspector

cd apps/server
pnpm inspect

Öffnet den MCP Inspector mit einem stdio-Unterprozess, um die Tools manuell zu testen.

HTTP / eigener Client

Der Streamable-HTTP-Transport wird unter POST /mcp auf demselben Port wie das Dashboard gemountet. Punkt jedes HTTP-aware MCP-Client auf http://127.0.0.1:7777/mcp und sendet Authorization: Bearer <your HEALTH_MCP_TOKEN>, wenn ein Token gesetzt ist.

Der erste OAuth-Link zu einem Wearable-Provider benötigt den laufende Server, um den Redirect in der nicht parrouten Route empfangen zu können. Sobald der Link hergestellt ist, bleben Refresh-Tokens in auth.json erhalten und der Stdio-Modus kann von dort aus unbegrenzt synchronieren.

Das Dashboard

Wird am / im selben Prozess ausgeliefert. Aktuelle SeitenElement:

• Today — Mahlzeiten des Tages, Summen gegen Ziele, Flüssigkeit, Gewicht

• Log — Benutzer, Mahlzeiten, Flüssigkeit, Gewicht, Körpermaße eintragen

• *Embed, ***, Batches — der Lebensmittel-Graph

• Runools — Makro-Grenzen, Gewichtsziel

• Labs — Panels, Ergebnisse, Trends, Infotexte pro Idiom

• Trends — wöchentliche Zusammenfassungen

• Wearables — Provider-Status, Schlaf / Aktivität / Lesebereitschaft / Tageswerte

• Insights — correlate-UI

• Settings — Token, Zeitzone, Theme

Sobald du TanStack Router + Query, Kumo UI auf Tailwind v4 und Recharts stehst du den Cookie. Der Dunkelmodus folgt standardmäßig dem OS; du kannst ihn unter Settings anpassen.

Konfiguration

Den Vorrang: CLI-Flag > Umgebungsvariable > JSON-Config-Datei > Standardwert.

Jedes Flag, jede Umgebungsvariable, das Schema der JSON-Config-Datei und um den VCS-Beschreibungselementen in docs/CONFIGURATION.md erläutert.

Datenschutz und Ästhetik

Der Server ist auf eine sichere Konfiguration ausgelegt.

• Standardmäßig nur Loopback. Für jeden anderen knot muss HEALTH_MCP_TOKEN eine mindestens 32 Zeichen lange Zufalls folgen (openssl rand -hex 32); sonst weigert der Server zu starten, um einen soft-Backup zu verhindern.

• data.db und auth.json werden mit 0 0600 in 0700-Verzeichnis erzeugt. Weitere Rechte verweigern die Verwendung des Dateiformats, falls du nicht --allow-insecure-db / --allow-insecure-auth angibt.

• Wearable-OAuth-Tokens stehen in ~/.health-mcp/auth.json, getrennt von data.db, damit health-mcp export die Analyse ohne Provider-Lecks exportieren kann. *. * Provider wie Wanna können Refresh-Token bei jeder Benutzung austauschen. Der Auth-Store serialisiert den Wechsel pro Anbieter, damit nicht zwei gleichzeit-401-Anfragen denselben Token verbrauchen und dich aussperren.

• Der OAuth-Callback verwendet einen HMAC-signierten State-Payload mit Ablauf nach 10 Minuten und einer einmaligungen Nonce in SQLite–Kein Replay.

Wogegen diese Schutz ein und was nicht, und wie du den Server sicher über localhost hinaus einsetzt (TLS-tunnel; Doctor-Ausgabe prüfen) steht in docs/OPPONENT.md.

build

Wie alles aufgebaut ist

Ein Node-Prozess. Eine Hono-App mountet den MCP Streamable-HTTP Transport under /mcp, den REST-Spiegel under /api/*, die Wearable-OAuth-Callback-Route unter /auth/wearable/callback und die Dashboard-SPA under /. Storage ist SQLite über better-sqlite3 mit PRAGMA journal_mode=WAL und PRAGMA foreign_keys=ON. Komplette Logik liegt in apps/server/src/services/*.ts; MCP-Tool-Handler and REST-Routen sind hülle Zod validierte Wrapper. Wearable-Daten laufen durch das WearableProvider-Interface, das einerseits roh hohe anbieter inputs und normalize-spezifisch über Hersteller hinweg in einer Transaktion pro sync-page schreibt.

Im HTTP-Modus zyklische Frage alle Sekunden oder konfigurierbarer Cron (*/30 * * * *) ruft syncWearables() für jeden verlinkten Provider auf. Im Stdio-Modus wird der Scheduler überspungen; Agents rufen sync_wearables on demand auf.

Die Unterteilung in Services, Transport despite durch den ArchitekturArtchiv in docs/ARCHITECTURE.md.

Tools-Oberfläche

Ungefähr 60 Tools. discover_capabilities gibt den vollständigen Katalog, gruppiert nach Bereich, mit aktuellen AktivierungFlags zurück, damit Agents ihn zuerst abrufen können, statt nach Uhse.

ping, discover_capabilities

# food
search_food, search_foods, lookup_barcode, get_food
create_custom_food, bulk_upsert_custom_foods, update_custom_food, delete_custom_food

# meals
log_meal, list_meals, get_meal, update_meal, delete_meal, undo_last_meal,
add_meal_component, update_meal_component, remove_meal_component

# recipes + batches
create_recipe, update_recipe, delete_recipe, list_recipes, get_recipe
create_batch, list_batches, get_batch, archive_batch, delete_batch

# remembered meals  (read tools hidden until you save one)
remember_meal, list_remembered_meals, get_remembered_meal,
update_remembered_meal, forget_meal, log_remembered_meal

# simple logs
log_hydration, list_hydration, delete_hydration
log_weight,    list_weight,    delete_weight
log_measurement, list_measurements, delete_measurement
get_goals, set_goals

# summaries
daily_summary, weekly_summary, range_summary

# biomarkers + labs
search_biomarker, get_biomarker, create_custom_biomarker, update_biomarker, set_optimal_range
log_lab_panel, log_lab_result, list_lab_results, latest_biomarkers, biomarker_trend
list_lab_panels, get_lab_panel, delete_lab_result, delete_lab_panel

# insights  (hidden until ≥7 days intake AND (≥1 wearable_daily row OR ≥3 lab_results))
correlate, list_correlate_metrics

# wearables  (most hidden until a provider is linked)
wearables_list_providers, wearables_status,
wearable_connect_url, wearable_disconnect, sync_wearables,
wearable_sleep, wearable_activity, wearable_readiness, wearable_daily, wearable_metric_minutes,
set_activity_type_map

# whoop  (hidden until linked)
whoop_recovery, whoop_cycles, whoop_sleep_raw, whoop_workouts_raw,
whoop_profile, whoop_body_measurement

Durch Capability-Gating bleiben Tools unsichtbar, wenn sie nicht genutzt werden können. Aber Wearable-Abfragen bleiben bis und zu einem verlinkten Provider unsichtbar; correlate bleibt so angibtich, bis genügend Daten vorliegen. Der vollständige Katalog mit Parametern, Rückgabeformen und Gruppierungsregeln unter docs/MCP.md to find.

Dokumentation

Wait, I wrote "Der Und brauchen..." – That's messed up. Need to review.

Correct bullet 4: "Neue Services brauchen einen Vitest‑Test ..." Not "Der Und". Good.

I see in my draft: "Keine keine Logik" – fix to "Keine Logik in Handler."

"Technische Schritt" – "Schritt‑für‑Schritt‑Anleitung" better.

"Versionshöhe" word is weird. Use "Versionserhöhung → Tag → npm (OIDC) + GHCR, alles in einem Actions‑Lauf". In table, symbols are okay. Let me finalize table entry: "Versionserhöhung → Tag → npm (OIDC) + GHCR, alles in einem Actions‑Lauf". Keep "v00".

Also "Tool‑Katalog, Capability‑Gates, Item‑Formen" – I want "Element‑Formen" or "Entry‑Formen". Actually "item shapes" – maybe "Elementformen", but "Item" is common in German tech. Use "Item‑Formen".

Now rewrite the "Contributing" section perfectly:

• Bullet 1: "Geschäftslogik lives in ..." – Should say "liegt". Good. "MCP tools and REST routes are thin wrappers" – "sind dünne Wrapper darum". "Don't put logic in handlers." – "Keine Logik in Handlern." Fix.

Let me write final:

• Geschäftslogik liegt in apps/server/src/services/. MCP‑Tools (src/mcp/tools/) und REST‑Routen (src/rest/) sind nur dünne Wrapper darum. Keine Logik in Handlern.

• Migrationen sind eingecheckte TypeScript‑Module unter apps/server/src/db/sql/000N-*.ts. Nur vorwärtsgerichtet.

• Gemeinsame Zod‑Schemas liegen in packages/shared. Server und Dashboard stimmen sich darauf ab.

• Neue Services zaunden einen Vitest‑Fall (*.test.ts) oder Abdeckung über die Integrationstest‑Suite (apps/server/src/integration.test.ts).

• Vor dem Pushen: pnpm lint:fix – Biome.

Note: "Vitest‑Fall" vs "Vitest‑Test". "Vitest-Fall" is weird; "Testfall" or "Vitest‑Test". I'll write "Vitest‑Test".

Also "nach" – "erne". Let's use "Neue Dienste" hmm “services” – we use "Services" itself. The example: "Neue Services brauchen ..." Good.

"Provider-Hinzufügen" paragraph:

"Das Hinzufügen eines neuen Wearable‑Providers ist eine in sich geschlossene Aufgabe: lege apps/server/src/wearables/providers/<id>/ an, ergänze eine Migration mit den Raw‑Spiegeltabellen und registriere den Provider im Wearable‑Registry. Die normalisierten Lese‑Tools übernehmen dann automatisch. Eine Schritt‑für‑Schritt‑Anleitung findest Du in docs/WEARABLES.md."

"Anleitung findest du" uses "du" – in German–German. Alternatively "Guidance". I'll use imperative "Ghar"? But "Walkthrough"->"Eine ausführliche Anleitung".

Release paragraph:

"Ein Release zu schneiden ist ein Ein‑Klick‑GitHub‑Actions‑Lauf – Versions-Upgrades, Tagging, npm‑Publish and GHCR‑Tags in einem Rutsch. Siehe docs..."

Use "entspricht" instead of "ist ein Ein‑Klick..." Fine.

Let me write: "Ein Release ist ein GitHub‑Actions‑Lauf mit einem Klick – Version erhöhen, Tag anlegen, npm‑Publish und GHCR‑Tags auf einmal." Good.

Status section, fix "mitizen" typo.

Now "Technik" – tech stack. Keep.

License section: okay.

At the end, the MIT link is MIT. The target original "; (no .md)". Keep.

Now let me prepare final answer carefully, and not accidentally use "thanks" etc.

I'll rewrite full German markdown in a natural and consistent way.

Keep "GXP10" verbatim.

One more nuance: in "raw mirror tables", "Mirror" is an English term; could be "Mirror" or "Spiegel". If we wrote "Raw‑Mirror‑Tabellen" that keeps "Mirror" which is mod name. Better German "Raw-Spiegeltabellen"? Actually "raw mirror" is "raw mirror tables" – maybe "Mirror-Tabellen" as technical. I'll use "Raw-Mirror-Tabellen" – acceptable tech jargon. Hmm. Since the instruction says "translate prose only", but the term "raw mirror" is a technical compound, and "mirror" is not listed, but it's a technical nuance. I'd choose "Raw‑Spiegeltabellen" for German. But "Raw" might stay because it's a separator. Actually "raw vs normalized" – in German "roh" vs "normalisiert". So "Rohdaten-Mirror-Tabellen"? Let me "Roh‑Mirror‑Tabellen". This sounds better: "Raw mirror" doesn't have a standard. Could use: "Roh-Spiegeltabellen". I'll translate "raw" as "Roh" and keep "Mirror" as "Spiegel"? To avoid weird, I'll use "Roh‑Spiegeltabellen". Hmm.

But the navigation table row: "SQLite‑Schema, Indizes, Roh‑ vs. normalisierte Wearable‑Daten" – that's good.

In text: "add a migration with the raw mirror tables" – "füge eine Migration mit den Roh-Spiegeltabellen ein." Could sound odd. Since "mirror" references the actual DB pattern "mirror tables". In German computer science, "Mirror" is used. "Roh‑Mirror‑Tabellen" is fine as a compound. Let's use "Roh-Mirror-Tabellen".

Check: "Idx" -> "File modes" -> "Dateimodi". Good.

"Bearer auth" – "Bearer-Authentifizierung" good.

"Loopback rule" – "Loopback-Regel" – German.

"oh oh oh".

Let me now write final answer with no backticks around the entire block.

Maybe I should avoid the table alignment to not break markdown. I'll just include the original dashes but no padding. I can copy online:

| Dokument                                   | Was es behandelt                                             |
| ------------------------------------------ | --------------------------------------------------------------- |
| [Architektur](./docs/ARCHITECTURE.md)      | ... |
...