convez.ai
MCP Server
nikira-studio

healthquery

nikira-studio/healthquery

Ver no GitHub
InicialPluginScore · de 0 a 100

Self-hosted personal health dashboard. Syncs from Android Health Connect via webhook, stores locally in SQLite, and visualizes steps, sleep, vitals, and more. Optional LLM for natural-language reports and an MCP server for AI assistant integration.

Instalação

$npx convez-ai nikira-studio/healthquery

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
9
Forks
2
Acompanhando
0
Saúde
50%
Último commit
há 3 dias
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

HealthQuery

A self-hosted personal health dashboard. Your phone syncs health data from Android Health Connect to a local server. You view it in a browser, generate structured reports, and optionally ask questions about your data using an LLM of your choice.

No cloud services required. Data stays on your own hardware.

HealthQuery overview

HealthQuery vitals


How it works

  1. An Android app (Real Life Dashboard Companion) reads your health data from Health Connect and posts it to your server via webhook.
  2. The backend stores it in a local SQLite database.
  3. You open a browser to view your steps, sleep, vitals, and body metrics; generate doctor-visit summaries; or ask natural-language questions about your data.

Prerequisites


Setup

1. Clone the repo

git clone https://github.com/your-username/healthquery.git
cd healthquery

2. Create your config

cp docker-compose.example.yml docker-compose.yml

Open docker-compose.yml and set two tokens. Generate them however you like — a password manager, openssl rand -base64 32, or any random string:

HEALTHQUERY_INGEST_TOKEN: your-ingest-token-here   # the companion app uses this
HEALTHQUERY_READ_TOKEN:   your-read-token-here      # the dashboard uses this

Keep these separate. The ingest token only permits writing health data. The read token only permits reading it.

3. Start the containers

docker compose up -d

The dashboard is now running on port 3135.

4. Set up a reverse proxy (recommended)

Point nginx, Caddy, or Traefik at http://localhost:3135. The frontend handles routing; all API calls go through /api/.

If you expose the server to the internet, use HTTPS.

5. Configure the companion app

See Data source below for how to point the app at your webhook URL and set the ingest token.


Data source

HealthQuery receives data from Real Life Dashboard Companion, an Android app that reads from Health Connect and posts to a configurable webhook.

In the companion app settings, set:

FieldValue
Webhook URLhttps://your-server/api/webhook/health
Auth headerX-Webhook-Token
Auth tokenyour ingest token

The companion app handles syncing schedules. After the first sync, your data appears in the dashboard.

What gets synced: steps, distance, calories, heart rate, resting heart rate, heart rate variability, SpO2, sleep sessions and stages, weight, body fat, workouts, and more.


Dashboard tabs

TabWhat it shows
Overview7-day step trend, latest snapshot, day-over-day comparisons
TimelineChronological feed of all health events
ActivityDaily steps, workout list
SleepSession list with stage breakdown
VitalsHeart rate, resting HR, HRV, SpO2 — latest reading per metric
BodyWeight, body fat, and other body composition metrics
DataRecord counts, recent ingest batches, sync status
ReportsStructured doctor-visit summary for a date range
AskNatural-language questions about your data (requires LLM)
SettingsConfigure LLM endpoint, view operational defaults

LLM setup (optional)

Without an LLM, Reports generates a structured text summary from your data. The Ask tab is hidden.

With an LLM, Reports can rewrite summaries in natural language and Ask answers free-form questions about your health data.

Configure it in the Settings tab — no rebuild needed. Or set environment variables in docker-compose.yml before the first start:

HEALTHQUERY_LLM_BASE_URL: https://api.openai.com/v1
HEALTHQUERY_LLM_MODEL:    gpt-4o-mini
HEALTHQUERY_LLM_API_KEY:  sk-...

Any OpenAI-compatible endpoint works. For a local model:

HEALTHQUERY_LLM_BASE_URL: http://ollama:11434/v1
HEALTHQUERY_LLM_MODEL:    llama3
HEALTHQUERY_LLM_API_KEY:  ""

Settings saved in the UI override environment variables without a container rebuild.


MCP server (optional)

HealthQuery includes an MCP server that exposes your health data to AI assistants like Claude Desktop.

The MCP server runs as a local stdio process and reads from your HealthQuery API. Configure it by pointing it at your server URL and read token:

HEALTHQUERY_BASE_URL=http://localhost:3135 \
HEALTHQUERY_READ_TOKEN=your-read-token \
python backend/mcp_server.py

For Claude Desktop, add to your claude_desktop_config.json:

{
  "mcpServers": {
    "healthquery": {
      "command": "python",
      "args": ["/path/to/healthquery/backend/mcp_server.py"],
      "env": {
        "HEALTHQUERY_BASE_URL": "http://localhost:3135",
        "HEALTHQUERY_READ_TOKEN": "your-read-token"
      }
    }
  }
}

Environment variables

All variables go in docker-compose.yml under healthquery-api → environment.

VariableRequiredDefaultDescription
HEALTHQUERY_INGEST_TOKENYes—Token the companion app sends with each sync
HEALTHQUERY_READ_TOKENYes—Token the dashboard uses to read data
HEALTHQUERY_AUTH_HEADERNoX-Webhook-TokenHeader the companion app sends the ingest token in
HEALTHQUERY_LOG_LEVELNoINFOLog verbosity (DEBUG, INFO, WARNING)
HEALTHQUERY_LLM_BASE_URLNo—OpenAI-compatible API base URL
HEALTHQUERY_LLM_MODELNo—Model name (e.g. gpt-4o-mini, llama3)
HEALTHQUERY_LLM_API_KEYNo—API key (leave blank for local models)
HEALTHQUERY_LLM_TIMEOUT_SECONDSNo60LLM request timeout
DB_PATHNo/app/data/healthquery.dbSQLite database path inside the container

The frontend build also takes two build args:

ArgDefaultDescription
VITE_API_BASE_URL/apiAPI base path (change if not using the built-in nginx proxy)
VITE_READ_TOKEN—Read token baked into the frontend build

Tech stack

Backend: Python 3.11, FastAPI, aiosqlite, SQLite (WAL mode), sqlglot (SQL guard), FastMCP

Frontend: React 19, TypeScript, Vite, Tailwind CSS, Recharts

Infrastructure: Docker, nginx (serves frontend + proxies /api/ to backend)


Data and privacy

All data is stored in a single SQLite file on your server. Nothing is sent to external services unless you configure an LLM endpoint.

The ingest and read tokens are separate by design. A compromised read token can't write data. A compromised ingest token can't read it.

The free-form SQL query endpoint (POST /api/health/query) runs queries through an AST whitelist that only permits single SELECT statements — no mutations, no ATTACH, no multi-statement execution.


Development

Backend

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
DB_PATH=./dev.db HEALTHQUERY_INGEST_TOKEN=dev HEALTHQUERY_READ_TOKEN=dev uvicorn main:app --reload

Frontend

cd frontend
npm install
VITE_API_BASE_URL=http://localhost:8000/api VITE_READ_TOKEN=dev npm run dev

Tests

cd backend && pytest

License

MIT

Ver o original no GitHub

Bom para

Relacionados