clincalc - open clinical calculators

Open source, community-auditable clinical calculators. One Rust crate is the scoring engine; every surface - CLI, MCP tool, REST API, desktop GUI, web UI, and embeddable Rust library - is driven from that single source of truth.

A score is computed once, in the core library, and the result is identical wherever it appears. Every calculator cites primary literature, is tested against published vectors, and records the licence it is distributed under.

Why

Clinicians need clinical digital tools to provide good care, but the incentives to build them into EHRs are weak and the compliance barriers are high. The result is a patchwork of calculators scattered across the web, often behind paywalls or implemented inconsistently. This project makes them open source, free to use, evidence-based, and auditable - each cites primary literature, is tested against published vectors, and records the licence it is distributed under.

'Soft interoperability'

'Soft interoperability' is a phrase coined by Marcus Baw (@pacharanero) to describe the everyday copy-and-paste interop which is used by clincians as a substitute for 'proper' interoperability: it lets clinicians use the tools they want without being constrained by their EHR. Copy-and-paste is derided as a kludge, but it is what clinicians actually use, so every calculator produces a clean, editable text summary as a first-class output - while also dispatching structured results when embedded in a host.

Install and use the clincalc CLI

After the first GitHub Release is published, the docs site hosts cargo-dist installer proxies:

curl -LsSf https://pacharanero.github.io/clincalc/install.sh | sh

powershell -ExecutionPolicy Bypass -c "irm https://pacharanero.github.io/clincalc/install.ps1 | iex"

Until then, install from source:

cargo install --git https://github.com/pacharanero/clincalc clincalc

There are no per-calculator flags. Every calculator is driven the same way - ask for a template, fill it in, pass it back:

clincalc list                       # list calculators (alias: ls)
clincalc tags                       # list tags with counts
clincalc calc <name>                # print a fillable input TEMPLATE (JSON)
clincalc calc <name> --schema       # the JSON Schema (full input contract)
clincalc calc <name> --license      # the algorithm's distribution licence + evidence URL
clincalc calc <name> --input -      # compute, reading JSON from stdin
clincalc calc <name> --input data.json   # ...or from a file
clincalc calc <name> --input '{...}'     # ...or inline

$ clincalc calc curb65 --input '{"confusion":false,"urea_mmol_l":8,"respiratory_rate":32,"systolic_bp":85,"diastolic_bp":55,"age":72}'
curb65 = 4
High severity ... consider hospital admission and assessment for intensive care.

The template printed by clincalc calc <name> has the same shape as the input it expects, so it is a clean round-trip. clincalc <name> remains supported as shorthand for clincalc calc <name>. Output, schema, and template are JSON on stdout; hints go to stderr.

MCP server

clincalc can also run as a local stdio MCP server when installed with the optional mcp feature:

cargo install --git https://github.com/pacharanero/clincalc clincalc --features mcp
clincalc mcp

The MCP server exposes every calculator as a typed tool named clincalc_<name> using the calculator's own JSON Schema. See docs/mcp.md for host configuration and safety notes.

Python package

Install from PyPI after the first release:

pip install clincalc

import clincalc

result = clincalc.calculate("bmi", {"weight_kg": 70, "height_cm": 175})
print(result["result"], result["interpretation"])

# Batch over a pandas DataFrame
import pandas as pd
results = clincalc.batch("bmi", pd.DataFrame({"weight_kg": [70], "height_cm": [175]}))

See docs/python.md for the full API and pandas helpers.

The library

The full UK-focused 50-tool roadmap (spec/calculator-roadmap.md) is implemented across five tiers, from QRISK3, PHQ-9, GAD-7, eGFR and FIB-4 through NEWS2, CURB-65, the Wells scores, CHA2DS2-VASc and HAS-BLED, to DAS28, SOFA, MELD, CHALICE and Gleason. Run clincalc list for the current set.

Proprietary tools are named, not hidden

A handful of tools cannot be shipped because they are proprietary or licence-locked (FRAX, MMSE, ELF, ACQ, the Oxford Hip/Knee Scores, CAT, MUST, CFS, LANSS). Rather than omit them silently, each is registered as a calculator that returns a structured explanation - the owner, why it cannot be shipped, open alternatives (often one shipped here), and how to advocate for open clinical tools:

$ clincalc calc frax --input '{}'
frax = unavailable: proprietary
FRAX ... is not available because it is proprietary or licence-locked. Owner:
University of Sheffield ... Open alternatives: qfracture ...

Architecture: one core, many surfaces

The dependency arrows all point into the core, which never depends on anything above it. All surfaces are additive - none requires a rewrite of the others.

The concrete Rust structure:

• clincalc (this crate) - the scoring engine. With default-features = false it is a strict leaf: only serde and serde_json, no async runtime, no host dependency.
• The default cli feature adds the clincalc binary and the reusable clincalc::cli module. A host CLI (e.g. GitEHR's gitehr calc) calls this module directly.
• The optional mcp feature adds clincalc mcp, a local stdio MCP server. Each calculator in clincalc::all() becomes a typed MCP tool automatically.
• The optional rest-api feature follows the same optional-feature pattern as mcp: clincalc api starts an axum server with an auto-generated OpenAPI spec.
• The clincalc Python package (python/) follows the same optional-dependency pattern, giving data-science workflows access to every calculator via PyPI without touching the Rust crate's dependency graph.

Adding a calculator to clincalc::all() surfaces it everywhere - CLI, MCP, REST API, GUI, web - with no per-surface code.

Input definitions

Several inputs are clinician-asserted predicates whose TRUE/FALSE conditions are easy to get subtly wrong (for example, "vascular disease" in CHA2DS2-VASc is arterial and excludes venous thromboembolism). Each such input carries a machine-readable definition - includes, excludes, a cited source, and a draft SNOMED ECL - that travels in the schema to every surface. See spec/calculator-input-definitions.md.

Embedding in a host (for example, GitEHR)

Any application can embed these crates. GitEHR (gitehr/gitehr) is one consumer: its CLI forwards gitehr calc to clincalc::cli::run, and a host MCP server can expose each calculator from clincalc::all() as a clincalc_<name> tool whose input schema is the calculator's own JSON Schema. The calculators are the engine; a host wires them into its own surfaces.

Develop

cargo test                                      # all calculators
cargo clippy --all-targets -- -D warnings
cargo fmt --all --check

CI enforces all three. Adding a calculator: implement it in clincalc (typed input, pure compute, build_response, a Calculator impl with input_schema() and license(), and literature-vector tests), register it in all(), and that is the only Rust work - the CLI and MCP surfaces pick it up automatically. See AGENTS.md, spec/calculators.md, spec/calculator-input-definitions.md, and the examples in examples/.

Licensing

• clincalc: AGPL-3.0-or-later. This work is deliberately not available for subsumption into proprietary EHRs; if that service needs to exist, it can be offered as a hosted Calc-API.
• Clinical algorithms are implemented from primary literature (most scores are public-domain methods); QRISK3 and QFracture are ported from ClinRisk's LGPL-3.0 source and carry the required disclaimer. Each calculator records its own distribution licence via clincalc calc <name> --license.
• Clinical content (source references) under CC-BY-SA-4.0.

Roadmap

See spec/roadmap.md for engineering, infrastructure, distribution, GUI, and product-level work, and spec/calculator-roadmap.md for the clinical-calculator backlog.