🩺 HealthLedger MCP

Your health record, on your machine. Let any AI read and reason over it — on your terms.

A local-first, model-agnostic Model Context Protocol server that stores your personal health data in a local SQLite file and hands back analysis-ready views, so any MCP client — and any LLM behind it — can log, retrieve, and reason over that record on demand.

✨ What it does

HealthLedger is a personal health ledger you run yourself. Install it wherever you want, point your AI client at it, and start adding your data. By default it runs as a local stdio server — nothing binds to the network and the record never leaves your machine.

Related MCP server: Withings MCP

🚀 Quick start

You need Python 3.11+. The fastest path uses uv (uvx runs it with zero install):

# Try it directly from the repo — no clone, no install:
uvx --from git+https://github.com/Cole-Will-I-Am/HealthLedger-MCP healthledger-mcp

Prefer a persistent install?

pipx install git+https://github.com/Cole-Will-I-Am/HealthLedger-MCP
# or, from a clone:
git clone https://github.com/Cole-Will-I-Am/HealthLedger-MCP && cd HealthLedger-MCP
pip install .
healthledger-mcp        # starts a local stdio server

That's it — no OAuth, no tunnel, no account. Your data is written to ~/.healthledger/health.db (override with HEALTH_MCP_DB).

🔌 Use it with any client / any model

HealthLedger speaks stdio MCP, so it drops into the standard mcpServers config that virtually every MCP client uses. Point your client at it and you're done — the model on the other side can be Claude, a local Llama, GPT-something, whatever your client runs.

Zero-install (uvx):

{
  "mcpServers": {
    "healthledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Cole-Will-I-Am/HealthLedger-MCP", "healthledger-mcp"]
    }
  }
}

After pipx/pip install:

{
  "mcpServers": {
    "healthledger": { "command": "healthledger-mcp" }
  }
}

• Claude Desktop → claude_desktop_config.json

• Cursor → .cursor/mcp.json · Zed → context_servers · Cline / Continue / LibreChat → their MCP settings

• Any other MCP client → the same command/args shape

Want it to hold more than one person? Pass a user label on any tool call (defaults to me, from HEALTH_MCP_DEFAULT_USER).

🗄️ Storage

• SQLite at ~/.healthledger/health.db — mode 0600, WAL journaling. Override with HEALTH_MCP_DB.

• Schema v4 covers quantitative metrics, events, notes, profile facts, conditions, allergies, medications & dose logs, lab reports/results, biomarkers, tumor/cancer records, encounters/physicals, procedures, imaging, immunizations, care tasks, documents, enriched family history, genomic/PGx records, reproductive-health records, substance-use logs, wearable/app sources, wearable samples, and a generic health_records catch-all.

• ~/.healthledger/audit.log records every tool call (override with HEALTH_MCP_AUDIT_LOG).

• It's just a SQLite file — back it up, sync it, or delete it like any other file.

Profile keys (stable facts only)

Recommended keys for clients: birth_date, sex, gender, height_cm, blood_type, emergency_contact, primary_care_provider, preferred_pharmacy, insurance, advance_directive_on_file, plus stable preferences/goals.

⏳ Time-varying data belongs in the dedicated tables, not in profile keys.

🧰 Tool catalog

78 tools, grouped by purpose. Every tool accepts an optional user label (default me, from HEALTH_MCP_DEFAULT_USER).

log_metric · get_metrics · list_metrics · analyze_metric · log_event · get_events · log_note · get_notes · set_profile · get_profile · delete_profile

add_condition · list_conditions · add_allergy · list_allergies · add_medication · list_medications · log_medication_taken · list_medication_schedule · list_medication_logs · add_encounter · list_encounters · add_procedure · list_procedures · add_imaging_report · list_imaging_reports · add_immunization · list_immunizations

add_lab_report · list_lab_reports · add_lab_result · list_lab_results · analyze_lab_trend · add_biomarker · list_biomarkers · analyze_biomarker_trend · add_tumor_record · list_tumor_records · add_document · list_documents · add_family_history · list_family_history · add_health_record · list_health_records

add_reproductive_record · list_reproductive_records · analyze_reproductive_trend · add_substance_use_log · list_substance_use_logs · analyze_substance_trend · add_wearable_source · list_wearable_sources · add_wearable_sample · import_wearable_samples · list_wearable_samples · analyze_wearable_trend

add_genomic_record · list_genomic_records

correlate_metrics · analyze_event_impact · align_series · normalize_series · analyze_trend

semantic_search · get_record · data_coverage

get_reasoning_guide returns the packaged reasoning guide; clients with MCP resource support can also read healthledger://skill/reasoning. Analysis tools guarantee top-level value, reference_range, recency, and source_ids keys, and analysis/summary/care-gap tools advertise statementType: descriptive.

add_care_task · complete_care_task · list_care_tasks · list_due_tasks · health_agenda · care_gap_report · summarize_health · search_records · delete_record · export_data · health_status

How the "smart" tools behave

Wearables, on purpose

Wearable imports are kept separate from ordinary metrics:

• wearable_sources identify the device / app / feed.

• wearable_samples store high-volume typed samples — steps, HRV, resting HR, workouts, sleep, SpO₂, calories, temperature, and similar.

• Use import_wearable_samples for bulk. Per call: up to HEALTH_MCP_MAX_WEARABLE_IMPORT_ROWS=500 samples and HEALTH_MCP_MAX_BULK_JSON_CHARS=200000 bytes of JSON.

⚙️ Configuration

Everything is environment variables. Defaults shown; the local-mode defaults need no setup.

Remote-mode-only (HEALTH_MCP_TRANSPORT=http): HEALTH_MCP_GITHUB_CLIENT_ID, HEALTH_MCP_GITHUB_CLIENT_SECRET, HEALTH_MCP_ALLOWED_LOGINS, HEALTH_MCP_PUBLIC_URL, HEALTH_MCP_HOST (127.0.0.1), HEALTH_MCP_PORT (8800), HEALTH_MCP_PATH (/mcp).

✅ Offline tests

From a clone (these touch neither your real database nor real GitHub credentials — they use a temp DB and dummy config):

python test_tools.py     # exercises the tools end-to-end
python test_wiring.py    # exercises the optional remote (OAuth) wiring

🌐 Remote mode (optional)

You don't need any of this to use HealthLedger — it's for people who want to reach one instance from a networked client (e.g. a web-based assistant) instead of running it locally. Set HEALTH_MCP_TRANSPORT=http and it becomes an OAuth-protected HTTP server:

client ──HTTPS──► reverse proxy / tunnel ──► 127.0.0.1:8800  (HealthLedger, http mode)
                        │                            │
                  GitHub OAuth                SQLite 0600 / WAL
                 (allow-list only)             + audit.log

• Binds 127.0.0.1 only; expose it via your own reverse proxy or a Cloudflare Tunnel.

• Auth: OAuth 2.1 via FastMCP's GitHub OAuth proxy. Only the GitHub logins in HEALTH_MCP_ALLOWED_LOGINS may connect — everyone else gets 401.

• Fail-closed: in http mode the process refuses to start without client id/secret and at least one allow-listed login. There is no open networked mode.

• Health check: an unauthenticated request returns 401 (up and guarded).

Live demo: a single-tenant instance runs at https://health-mcp.manticthink.com/mcp (allow-listed to the maintainer). It's there to show the remote path working — to actually use HealthLedger, run your own local copy per Quick start.