Aion Bridge MCP

Connect Claude Code (and other MCP clients) to your personal health data via the Aion local FHIR bridge. Everything stays on your local network — no cloud, no servers, no data leaving your home.

Source-available under PolyForm-Noncommercial-1.0.0 — free for personal and non-commercial use. Commercial use requires a license from Bionic Light Industries.

How it works

Your phone (Aion app)
    ↕  WebSocket on local WiFi (port 8420, wss)
Your PC (this MCP server)
    ↕  stdio
Claude Code / Cursor / Windsurf / …

Claude gets tools to query your FHIR health records (vitals, labs, conditions, medications, and more) and can reason about them directly.

Quickstart

Fastest — npx (no install)

npx -y @aion-health/bridge setup

This auto-detects your installed AI clients (Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, Zed), finds your phone on the local network, and writes the right config for each. The published package is a single self-contained file — no dependencies to install.

Alternative — Aion Desktop companion

The Aion Desktop app ships this MCP server bundled, finds your phone, and writes .mcp.json for every detected client. Open Aion Desktop → Connect → "Set up AI clients" and pick a launch method:

• npx (default) — config runs npx -y @aion-health/bridge.
• Bundled binary — config points at the executable inside the installed app. No Node.js required.

From a checkout

npm install
npm run build && npm run bundle
node dist-bundle/aion-health.cjs setup

The wizard auto-detects installed clients (Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, Zed) and writes their configs, plus prints manual snippets for Continue.dev and OpenAI Codex.

Prerequisites

1. Aion app installed on your phone, with data synced
2. Phone and PC on the same WiFi network (or connected over USB — see below)
3. Bridge running: Aion app → Settings → Bridge → Start Bridge
4. The 6-digit pairing code shown in the app

.mcp.json reference

After running setup, your AI client uses this config automatically. To configure manually:

{
  "mcpServers": {
    "aion-health": {
      "command": "npx",
      "args": ["-y", "@aion-health/bridge"],
      "env": {
        "AION_BRIDGE_URL": "wss://192.168.1.100:8420",
        "AION_PAIRING_CODE": "123456"
      }
    }
  }
}

For the bundled-binary launch method, command is the absolute path to the executable and args is empty.

AION_BRIDGE_URL is optional — if omitted, the server auto-discovers your phone via Bonjour/mDNS, the ARP cache, and a TCP subnet scan.

Available tools

| Tool | Description | |-----------------------|-------------------------------------------------------------------------| | fhir_summary | Counts of all FHIR resources by type — call first | | fhir_query | Query a resource type with the full predicate surface | | fhir_get | Fetch a single resource by type + id | | fhir_record | Record a new Observation | | analyze_health | Natural-language question answered by an LLM via the bridge (AION_ANALYZE_*) | | export_health_data | Full FHIR R4 Bundle export | | health_graph_report | Natural-language report over the health knowledge graph | | health_audit | Recent bridge audit log |

CLI subcommands

npx @aion-health/bridge setup      # Interactive setup wizard
npx @aion-health/bridge repair     # Update the pairing code after a bridge restart
npx @aion-health/bridge discover   # Scan for the phone, print its URL
npx @aion-health/bridge export     # Write a FHIR Bundle to stdout or --output file

It also doubles as a direct-to-bridge CLI (uses AION_BRIDGE_URL + AION_PAIRING_CODE, no server needed):

npx @aion-health/bridge summary                                   # counts by type
npx @aion-health/bridge query Observation --category vital-signs --limit 20
npx @aion-health/bridge query Condition --json > conditions.json  # raw FHIR
npx @aion-health/bridge get Observation obs-123
npx @aion-health/bridge count Observation
npx @aion-health/bridge analyze "Any concerning trends in my labs?"
npx @aion-health/bridge graph                                     # knowledge-graph report
npx @aion-health/bridge audit --limit 30

USB mode (no WiFi): npx @aion-health/bridge setup --usb, with iproxy 8420 8420 (iOS) or adb forward tcp:8420 tcp:8420 (Android) running — or let Aion Desktop manage USB automatically.

Build standalone binaries

npm install      # dev deps (esbuild + pkg + the shared lib)
npm run pkg:all  # builds all 5 platform binaries → bin/

The binaries embed the entire server (the shared @aion-health/core library and ws are inlined at bundle time), so they run with no node_modules present.

Development

This package consumes @aion-health/core (the shared bridge protocol / WebSocket client / discovery / MCP-client config) via a file: dev dependency on ../shared. The build (npm run build && npm run bundle) inlines it into a single dist-bundle/aion-health.cjs — that bundle is the published bin and has zero runtime dependencies. Run npm run build in ../shared first if you change it. Source lives in the Aion monorepo.

License

Source-available under PolyForm-Noncommercial-1.0.0. Free for personal and non-commercial use. Commercial use requires a license from Bionic Light Industries.