# MedlinePlus MCP

Open-source Model Context Protocol server for [MedlinePlus Connect](https://medlineplus.gov/medlineplus-connect/), the U.S. National Library of Medicine service for linking clinical codes and medication names to patient-friendly health information.

This server gives an AI agent narrow tools for looking up public MedlinePlus education links. It is intentionally not a medical-record server and does not store patient data.

## Why

Agents working near health records need trustworthy reference material, but they should not invent medication side effects, lab explanations, or condition summaries from memory.

`medlineplus-mcp` keeps the privacy boundary simple:

- Send generic lookup terms or codes to MedlinePlus, such as `metformin`, an RXCUI, an NDC, a LOINC code, an ICD-10-CM code, a CPT code, or a SNOMED CT code.
- Keep private chart context local in your own agent or application.
- Merge public education links with private patient context only after the lookup result comes back.

## Tools

### `lookup_medication`

Look up medication education links using:

- `name`: English medication name fallback, such as `metformin`
- `rxcui`: RxNorm Concept Unique Identifier
- `ndc`: National Drug Code
- `language`: `en` or `es`

Spanish medication responses generally require RXCUI or NDC.

### `lookup_diagnosis`

Look up diagnosis/problem education links using:

- `code`: ICD-10-CM, ICD-9-CM, or SNOMED CT code
- `codeSystem`: `icd10cm`, `icd9cm`, or `snomedct`
- `name`: optional display name
- `language`: `en` or `es`

### `lookup_lab_test`

Look up lab-test education links using:

- `loinc`: LOINC code
- `name`: optional display name
- `language`: `en` or `es`

### `lookup_procedure`

Look up procedure education links using:

- `code`: CPT or SNOMED CT code
- `codeSystem`: `cpt` or `snomedct`
- `name`: optional display name
- `language`: `en` or `es`

### `medlineplus_connect`

Low-level escape hatch for supported MedlinePlus Connect request types.

## Install

```sh
git clone https://github.com/chrisvo/medlineplus-mcp.git
cd medlineplus-mcp
npm install
npm test
```

## Run

```sh
npm start
```

Example MCP config:

```json
{
  "mcpServers": {
    "medlineplus": {
      "command": "node",
      "args": ["/absolute/path/to/medlineplus-mcp/src/server.mjs"],
      "cwd": "/absolute/path/to/medlineplus-mcp",
      "env": {
        "MEDLINEPLUS_CACHE_TTL_MS": "43200000"
      }
    }
  }
}
```

`MEDLINEPLUS_CACHE_TTL_MS` defaults to 12 hours.
`MEDLINEPLUS_CACHE_DIR` defaults to `.cache/medlineplus-mcp`; set it to `off` to disable persistent disk caching.

## Caching

The server uses two cache layers:

- in-memory cache for repeated lookups during the current process,
- filesystem cache so repeated lookups survive process restarts.

By default cache files are written under `.cache/medlineplus-mcp/` in the server working directory. Cache keys are SHA-256 hashes of the MedlinePlus Connect request URL, and cached payloads contain only the public response from MedlinePlus plus the generic lookup request.

For a different cache folder:

```sh
MEDLINEPLUS_CACHE_DIR=/var/cache/medlineplus-mcp npm start
```

To disable disk caching:

```sh
MEDLINEPLUS_CACHE_DIR=off npm start
```

## Output

Tool responses are JSON text payloads:

```json
{
  "request": {
    "type": "drug",
    "codeSystem": "ndc",
    "code": "",
    "name": "metformin",
    "language": "en"
  },
  "query_url": "https://connect.medlineplus.gov/service?...",
  "attribution": "U.S. National Library of Medicine",
  "updated": "2026-07-18T03:05:36Z",
  "total_results": 1,
  "entries": [
    {
      "title": "Metformin",
      "url": "https://medlineplus.gov/druginfo/meds/a696005.html",
      "summary": "",
      "source": "American Society of Health-System Pharmacists, Inc."
    }
  ]
}
```

## Privacy

Do not send private chart notes, diagnoses, full medication administration records, names, MRNs, dates of birth, or free-form patient narratives to this server unless you are intentionally sending them to MedlinePlus Connect.

Prefer generic lookups:

- Good: `metformin`
- Good: `rivaroxaban`
- Good: `4548-4` for a LOINC lookup
- Bad: an entire hospital progress note

## Acceptable Use

MedlinePlus says Connect requests should stay under 100 requests per minute per IP address and recommends caching results for 12-24 hours. This server includes in-memory and disk caching by request URL.

See the official docs:

- [MedlinePlus Connect](https://medlineplus.gov/medlineplus-connect/)
- [MedlinePlus Connect Web Service](https://medlineplus.gov/medlineplus-connect/web-service/)
- [Technical Information](https://medlineplus.gov/medlineplus-connect/technical-information/)
- [MedlinePlus for Developers](https://medlineplus.gov/about/developers/)

## Medical Safety

MedlinePlus content is patient education, not a clinical decision engine. Agents using this MCP should:

- cite returned MedlinePlus links,
- separate public general education from patient-specific interpretation,
- avoid telling users to stop, start, or change medications,
- suggest questions for the care team when private clinical context matters.

## License

MIT