chartfold

Patient-facing tool for consolidating personal health data from multiple EHR (Electronic Health Record) systems into a single SQLite database. Query, analyze, and export your aggregated clinical data via CLI, MCP server (for LLM-assisted analysis), or self-contained HTML SPA.

Goal: Patient empowerment through data ownership — enabling time-series analysis, intelligent querying with tools like Claude Code, and organized preparation for medical visits.

Features

• Multi-EHR data consolidation — Import from Epic MyChart, MEDITECH Expanse, and athenahealth
• SQLite database — 17 clinical tables with full audit trail
• MCP server — 25 tools for LLM-assisted analysis with Claude
• Export formats — Self-contained HTML SPA, Arkiv (JSONL + README.md + schema.yaml)
• AI chat — Ask questions about your record in the HTML SPA via Claude, with inline charts (optional, requires proxy)
• Visit prep — See what’s new since your last visit, directly in the SPA
• Print summary — One-page printable view for your doctor
• Personal notes — Tag and annotate any clinical record

Installation

pip install chartfold

# With MCP server support (for Claude integration)
pip install "chartfold[mcp]"

Development Setup

git clone https://github.com/queelius/chartfold.git
cd chartfold
pip install -e ".[dev,mcp]"

Quick Start

Load Data from EHR Exports

# Load from individual sources
chartfold load epic ~/exports/epic/
chartfold load meditech ~/exports/meditech/
chartfold load athena ~/exports/athena/

# Or load all at once
chartfold load all \
  --epic-dir ~/exports/epic/ \
  --meditech-dir ~/exports/meditech/ \
  --athena-dir ~/exports/athena/

Query and Inspect

# View database summary
chartfold summary

# Run SQL queries
chartfold query "SELECT test_name, value, result_date FROM lab_results ORDER BY result_date DESC LIMIT 10"

# What's new since your last visit
chartfold diff 2025-01-01

Export Your Data

# Self-contained HTML SPA with embedded SQLite (all data stays client-side)
chartfold export html --output summary.html
chartfold export html --output summary.html --embed-images --config chartfold.toml
chartfold export html --output summary.html --ai-chat --proxy-url https://proxy.example.com/v1/messages

# Arkiv universal record format — primary backup/restore (round-trip capable)
chartfold export arkiv --output ./arkiv/
chartfold export arkiv --output ./arkiv/ --embed          # inline base64 assets
chartfold export arkiv --output ./arkiv/ --exclude-notes

# Import from arkiv archive
chartfold import ./arkiv/ --db new_chartfold.db
chartfold import ./arkiv/ --validate-only
chartfold import ./arkiv/ --db existing.db --overwrite

AI Chat (Optional)

The HTML SPA export can include an AI chat interface that lets you ask natural-language questions about your medical record. The LLM runs SQL queries against the embedded database — all patient data stays in your browser.

chartfold export html --output summary.html --ai-chat --proxy-url https://proxy.example.com/v1/messages

Requirements:

• A CORS proxy that forwards requests to the Anthropic Messages API (injects your API key and sets the model server-side)
• The proxy URL can also be configured in the SPA via the “Proxy settings” link

The system prompt includes the full database schema, summary statistics, and any analyses marked status: "current" in their frontmatter. The chat interface supports multi-turn conversation with an agent loop — the LLM can issue multiple SQL queries per question and render inline charts for trend visualization.

Visit Prep

The SPA includes a “Visit Prep” section that auto-detects your most recent encounter date and shows everything new since then: lab results, encounters, medications, imaging, clinical notes, conditions, procedures, pathology, and genetic variants. The date is editable for custom ranges.

Print Summary

The “Print Summary” section generates a one-page printable view with patient demographics, active conditions, active medications, recent labs with trend indicators, and last 3 encounters. Click “Print” or use Ctrl+P to print or save as PDF.

Personal Notes

# List recent notes
chartfold notes list --limit 20

# Search by tag or query
chartfold notes search --tag oncology --query "CEA"

# Search by reference (notes linked to specific records)
chartfold notes search --ref-table lab_results

Supported EHR Sources

Expected Input Directory Structures

Epic:      input_dir/DOC0001.XML, DOC0002.XML, ...
MEDITECH:  input_dir/US Core FHIR Resources.json
           input_dir/CCDA/<uuid>.xml
athena:    input_dir/Document_XML/*AmbulatorySummary*.xml

Database Schema

chartfold stores data in 17 clinical tables:

All dates are stored as ISO YYYY-MM-DD strings. Every record carries a source field for provenance tracking.

MCP Server

chartfold includes an MCP (Model Context Protocol) server with 25 tools for LLM-assisted health data analysis:

chartfold serve-mcp --db chartfold.db

Available Tools

Clinical data is read-only (?mode=ro enforced at the SQLite engine level). Write operations are limited to personal notes and structured analyses.

Claude Code Configuration

Drop a .mcp.json in any directory where you run Claude Code:

{
  "mcpServers": {
    "chartfold": {
      "command": "python",
      "args": ["-m", "chartfold", "serve-mcp", "--db", "/path/to/chartfold.db"]
    }
  }
}

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "chartfold": {
      "command": "python",
      "args": ["-m", "chartfold", "serve-mcp", "--db", "/path/to/chartfold.db"]
    }
  }
}

Configuration

Generate a personalized config from your data:

chartfold init-config

This creates chartfold.toml with lab tests to chart based on what’s in your database:

[[lab_tests]]
name = "CEA"
match = ["CEA", "Carcinoembryonic Antigen"]

[[lab_tests]]
name = "Hemoglobin"
match = ["Hemoglobin", "Hgb", "HGB"]

Architecture

chartfold uses a three-stage pipeline for each EHR source:

Raw EHR files (XML/FHIR)
    ↓
[Source Parser]  → source-specific dict
    ↓
[Adapter]        → UnifiedRecords (normalized dataclasses)
    ↓
[DB Loader]      → SQLite tables

Key Design Decisions

• Idempotent loading — Re-running load for a source replaces its data
• Cross-source deduplication — Adapters deduplicate records using composite keys
• Date normalization — All dates normalized to ISO format at adapter stage
• Provenance tracking — Every record tracks its source for cross-source analysis

Testing

# Run all tests (1120+ tests)
python -m pytest tests/

# Run a single test file
python -m pytest tests/test_adapters.py

# Run with coverage
python -m pytest tests/ --cov=chartfold --cov-report=term-missing

Project Structure

src/chartfold/
├── sources/        # EHR-specific parsers (epic.py, meditech.py, athena.py, mhtml_*.py)
├── adapters/       # Normalize to UnifiedRecords (epic_adapter.py, etc.)
├── analysis/       # Query helpers (lab_trends.py, medications.py, etc.)
├── extractors/     # Specialized parsers (labs.py, pathology.py)
├── core/           # Shared utilities (cda.py, fhir.py, utils.py)
├── mcp/            # MCP server (server.py)
├── spa/            # HTML SPA export with embedded SQLite (sql.js) and optional AI chat
├── db.py           # Database interface
├── models.py       # Dataclass models
├── config.py       # Configuration management
├── cli.py          # Command-line interface
├── export_arkiv.py # Arkiv export (JSONL + README.md + schema.yaml)
└── import_arkiv.py # Arkiv import with validation and FK remapping

Adding a New EHR Source

1. Create sources/newsource.py with process_*_export(input_dir) returning a dict
2. Create adapters/newsource_adapter.py with *_to_unified(data) -> UnifiedRecords
3. Add a SourceConfig in sources/base.py
4. Wire into cli.py (add subcommand)
5. Add tests in tests/

Requirements

• Python 3.11+ (uses tomllib from stdlib)
• Dependencies: lxml, pyyaml
• Optional: mcp (FastMCP) for MCP server

License

MIT