# lab-units-mcp

An [MCP](https://modelcontextprotocol.io) server that converts clinical blood-test
results between conventional and SI units, and resolves lab-marker names — including
abbreviations and non-English labels — to a canonical analyte.

I built the first version of this while wiring up a pipeline that ingested blood
panels from several different labs. Half of them reported glucose in mg/dL and half
in mmol/L, HbA1c came back as either a percentage or mmol/mol, and the marker names
were inconsistent across providers and languages. The conversion factors are not
complicated, but keeping them correct and in one place — with the name-matching that
has to happen before you can convert anything — was worth pulling out into a small,
testable tool. This is that tool, exposed over MCP so an assistant can call it directly.

It is a units-and-naming utility. It does not interpret results, does not carry
reference ranges, and is not medical advice.

## Tools

| Tool | What it does |
|------|--------------|
| `convert_lab_value` | Convert a value between two units of the same analyte (e.g. glucose `mg/dL` ↔ `mmol/L`, HbA1c `%` ↔ `mmol/mol`). |
| `identify_analyte` | Resolve a printed label (`ЛПНП`, `A1c`, `glu`) to a canonical analyte and its available units. |
| `list_analytes` | List every supported analyte with its canonical unit and unit options. |

The analyte can be passed by name or by a common synonym in English or Russian, so
`glucose`, `Glucose` and `глюкоза` all resolve to the same marker.

## Supported analytes

Glucose, total/HDL/LDL cholesterol, triglycerides, creatinine, urea, total bilirubin,
uric acid, calcium, iron, magnesium, phosphate, haemoglobin, HbA1c, albumin, total
protein, C-reactive protein, testosterone, estradiol, cortisol, free T4, free T3,
vitamin D (25-OH), vitamin B12, folate, insulin, sodium, potassium and chloride.

Conversion factors are the standard molar-mass-derived values used across clinical
laboratories. HbA1c uses the NGSP ↔ IFCC relationship
(`mmol/mol = (% − 2.152) × 10.931`).

## Install

```bash
npm install -g lab-units-mcp
```

Or run it without installing:

```bash
npx lab-units-mcp
```

## Use it with Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "lab-units": {
      "command": "npx",
      "args": ["-y", "lab-units-mcp"]
    }
  }
}
```

There are no API keys and no network calls — everything runs locally.

## Use it with the Claude Code CLI

```bash
claude mcp add lab-units -- npx -y lab-units-mcp
```

## Examples

```
convert_lab_value  analyte="glucose"  value=99  from_unit="mg/dL"
  -> 99 mg/dL = 5.494 mmol/L (Glucose)

convert_lab_value  analyte="HbA1c"  value=5.7  from_unit="%"  to_unit="mmol/mol"
  -> 5.7 % = 38.79 mmol/mol (HbA1c)

identify_analyte   label="ЛПНП"
  -> ЛПНП -> LDL cholesterol (key: ldl_cholesterol); units: mmol/L, mg/dL
```

## Develop

```bash
npm install
npm run build
npm start
```

## License

MIT