Skip to main content
Glama
Open Drug Data MCP
by knorby
README.md
# Open Drug Data MCP

[![Codecov](https://codecov.io/gh/knorby/open-drug-data-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/knorby/open-drug-data-mcp)
[![Tests](https://github.com/knorby/open-drug-data-mcp/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/knorby/open-drug-data-mcp/actions/workflows/tests.yml)
[![npm version](https://img.shields.io/npm/v/@knorby/open-drug-data-mcp.svg)](https://www.npmjs.com/package/@knorby/open-drug-data-mcp)
[![MCP](https://img.shields.io/badge/MCP-server-6E56CF)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.knorby%2Fopen-drug-data-mcp/versions)
[![Node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-7.0-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/github/license/knorby/open-drug-data-mcp.svg)](https://github.com/knorby/open-drug-data-mcp/blob/main/LICENSE)

One research interface over open drug, supplement, and cosmetic data. A local
MCP server that searches public databases by the kind of value you have,
resolves identifiers across them, fetches full records with citations, and
pulls literature and classification references.

The server is read-only, runs over stdio, and is launched by an MCP host. It
does not cache, mirror, or redistribute any dataset.

## Quick start

### With an MCP host

Add the server to an MCP host. Most hosts accept a JSON block shaped like
this (see your host's documentation if it nests servers under a different
key):

```json
{
  "mcpServers": {
    "open-drug-data": {
      "command": "npx",
      "args": ["-y", "@knorby/open-drug-data-mcp"],
      "env": {
        "OPENFDA_API_KEY": "your-key",
        "DSLD_API_KEY": "your-key"
      }
    }
  }
}
```

Both keys are optional. Omit the `env` block entirely if you have neither;
keyless access works at a lower upstream rate limit.

Run `drugdata_ping` after connecting. It reports the server version, which
sources are enabled, and whether each source's optional key is configured —
never a key value.

### Agent skills

```bash
npx skills add knorby/open-drug-data-mcp
```

Installs the bundled skills for source-guided search → resolve → get research
and structured, cited product and ingredient reports.

### From a local checkout

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

Point the host at the built entrypoint instead:

```json
{
  "mcpServers": {
    "open-drug-data": {
      "command": "node",
      "args": ["/absolute/path/to/open-drug-data-mcp/dist/index.js"]
    }
  }
}
```

## Not medical advice

**Informational and research use only — not medical advice.**

This server does not diagnose, treat, prescribe, or recommend anything. It
returns what public databases publish, and those databases carry their own
limits: openFDA data is unvalidated, supplement labels are manufacturer
statements, adverse-event reports do not establish causation, and regulatory
listings are not a determination of safety or approval. Always consult a
qualified physician, pharmacist, or other licensed professional before making
a health decision, and read the operative regulation or product labeling
rather than relying on a database summary.

The data comes from public sources with their own terms. Full disclaimers,
licenses, attribution requirements, and source caveats are in
[`docs/SOURCES.md`](docs/SOURCES.md).

## What it does

- **Search by what you have.** A product name, brand, ingredient, barcode, or
  NDC; an ingredient name, INCI name, UNII, CAS number, EC number, RxCUI, or
  PubChem CID. You never choose a database first — the server fans out to
  every source that can answer, then groups records into evidence-based entities.
- **Resolve identity across sources.** One call walks the cross-source
  identity chain and returns trusted `links` (direct or derived) plus labeled
  `candidates` where the match is ambiguous. A link needs a direct identifier
  hit or a single top-tier name match; several plausible records stay
  candidates, and the chain never silently picks one.
- **Fetch the full record.** Product and ingredient lookups return the owning
  database's record, its identifier crosswalk, deep links, and suggested next
  calls.
- **Follow the literature and classifications.** A reference search covers
  PubMed, ClinicalTrials.gov, MeSH, MedlinePlus (topics, Genetics, Connect),
  UMLS, RxClass, and RxNorm's prescribable name list by name or identifier,
  returning titles, identifiers, and deep links — citations, not extracted
  article text.
- **Stay attributable.** Every result is credited to the upstream database
  with a deep link and a retrieval timestamp. Client libraries are never named
  in tool output.

The loop is **search → resolve → get**, plus a reference step for literature
and classification sources. Every search and resolution ends with
`nextSteps`, so an agent can continue without inventing an identifier.

## Environment variables

| Variable | Default | Purpose |
| --- | --- | --- |
| `OPENFDA_API_KEY` | unset | Optional openFDA key. Raises the upstream rate limit; keyless requests work. |
| `DSLD_API_KEY` | unset | Optional NIH DSLD key (from data.gov). Raises the limit from 1,000 to 10,000 requests per hour. Keyless requests work. |
| `UMLS_API_KEY` | unset | Required for the UMLS reference source only. A free UTS account API key under the UMLS Metathesaurus license. Without it, other sources work and the UMLS reference source returns a configuration error naming this variable. |
| `NLM_PUBMED_API_KEY` | unset | Optional NCBI E-utilities key for PubMed. Raises the rate limit. |
| `NLM_PUBMED_EMAIL` | unset | Optional contact address NCBI asks distributed software to send with PubMed requests. |
| `NLM_PUBMED_TOOL` | unset | Optional tool name NCBI asks distributed software to send with PubMed requests. |
| `DRUGDATA_TIMEOUT_MS` | `30000` | Per-request upstream timeout in milliseconds. Must be a positive integer when set; a blank value counts as unset. |
| `DRUGDATA_SEARCH_TIMEOUT_MS` | `45000` | Shared wall-clock deadline for search fan-out and enrichment. Returns completed results with source timeout statuses and `partial` when incomplete. Positive integer; blank means default. Does not change by-source lookup timeouts. |
| `DRUGDATA_DISABLED_SOURCES` | unset | Comma-separated adapter ids to switch off: `openfda`, `cosing`, `nlm`, `drugcentral`, `dsld`, `inkeedecoder`. `nlm` covers every NLM namespace (RxNorm, RxTerms, RxClass, DailyMed, MeSH, PubMed, MedlinePlus, UMLS, ClinicalTrials.gov) and the PubChem adapter, which shares the NLM client. Applies to searches, lookups, resolution, and reference searches. Unknown ids are a configuration error. |

Configuration is read lazily when a tool runs, never at startup. A
misconfigured server still answers `tools/list` and explains the problem
through a tool result. Blank API-key values count as unset, and a blank
`DRUGDATA_TIMEOUT_MS` falls back to the default; a non-blank value must be a
positive integer.

## Tools

| Tool | Inputs | Returns |
| --- | --- | --- |
| `drugdata_ping` | optional `message` | Server name/version, every source's enabled state and whether its key is configured (including UMLS and PubMed reference keys), never a key value. No network. |
| `drugdata_search_products` | `type`: `name`, `brand`, `ingredient`, `barcode`, `ndc`; `query`; optional `category`: `medication`, `supplement`, `cosmetic`; `resolve_identities` (default `false`); `page`; `response_format` | Product entities with original source records, confirmed links, conflicts, candidates, per-entity next steps, source statuses, coverage, and `partial`. |
| `drugdata_search_ingredients` | `type`: `name`, `inci`, `unii`, `cas`, `ec`, `rxcui`, `cid`; `query`; `resolve_identities` (default `false`); `page`; `response_format` | Ingredient entities with source-attributed identity evidence and the same coverage/status contract. PubChem answers name and CID searches. |
| `drugdata_get_product` | `source`: `openfda`, `dsld`, `dailymed`, `inkeedecoder`; `id`; `include_label_sections` (default `false`); `include_ingredients` (default `true`); `include_ingredient_enrichment` (default `false`); `page`; `response_format` | One product record, its ingredient rows and roles, source-specific details, links, and next steps. DailyMed usage sections and DSLD nutrient CAS/group enrichment are opt-in. |
| `drugdata_get_ingredient` | `source`: `openfda`, `cosing`, `drugcentral`, `nlm`, `inkeedecoder`, `pubchem`; `id`; `include_clinical` (default `false`); `include_cosing_panel` (default `false`); `response_format` | One ingredient profile: identifiers, names, functions, regulatory notices, clinical assertions, chemistry (PubChem), RxTerms presentation (RxNorm), links, and next steps. DrugCentral clinical data and the INKEEDecoder CosIng panel are opt-in. |
| `drugdata_resolve_identifiers` | exactly one of `unii`, `ndc`, `rxcui`, `cid`, `cas`, `inci_name`, `substance_name`, `spl_setid`, `dsld_id`; `include_label_ingredients` (default `false`); `resolve_ingredients` (default `false`); `max_candidates` (default `5`); `response_format` | An identity graph for an ingredient, or a product's cross-source links plus its ingredient rows. `links` are trusted; `candidates` need judgment. |
| `drugdata_search_references` | `source`: `prescribable`, `rxclass`, `mesh`, `pubmed`, `medlineplus`, `medlineplus_genetics`, `medlineplus_connect`, `umls`, `clinicaltrials`; `type`: `name` (default), `rxcui`, `ndc`, `cui`; `query`; `limit` (default `10`); `cursor`; `response_format` | Titles, identifiers (PMID, NCT, MeSH id, CUI, RxCUI, class id), and deep links from one NLM reference source per call. Paginated sources return an opaque `cursor`. UMLS requires `UMLS_API_KEY`. |

Pagination is per call. One `page` applies to every source in a search
fan-out, and each entry in `sources` reports its own `hasMore`. Lookups page their own
collections. Reference searches page through the `cursor` the previous
response returned. Nothing walks pages automatically.

Every result carries `structuredContent` validated against a closed schema,
plus a readable markdown text block. Search, lookup, and resolve tools accept
`response_format`; set it to `json` if a host wants JSON in the text block
too.

## Choosing the next call

- Start free text with `type: "name"`. Use `brand` deliberately for a
  brand-only search: fewer sources support it. Pass a product `category` when
  known; ingredient searches have no category filter.
- Read `entities`, not the old `groups` field. Each entity contains original
  `records`, combined `identifiers`, resolver-confirmed `links`, grouping
  `evidence`, source-attributed `conflicts`, unconfirmed `candidates`,
  optional source-attributed resolution `errors`, `resolution`, and executable
  `nextSteps` for every source record. Names
  alone never merge records. Ingredients can join by UNII, RxCUI, dashed CAS,
  CID, or InChIKey; products by full package NDC, SPL set id, or UPC — not
  their ingredient RxCUI or application number.
- Search defaults to lightweight evidence without identity resolution. Opt in
  with `resolve_identities: true` to enrich at most **five initial entities**,
  with **three concurrent resolutions**, within one **45-second default deadline**. `sources` reports
  `ok`, `error`, or `timeout`, page, `hasMore`, and `resultCount`. `coverage`
  reports entity/record counts, attempted/completed resolutions, and whether
  the cap applied. Unrequested resolution has zero counts and is not partial.
  `partial` signals failed/timed-out sources or requested but incomplete
  enrichment, or response-budget omissions. Zero matches with `hasMore: true`
  is still a successful page.
- For an existing source+id, call `drugdata_get_product` or
  `drugdata_get_ingredient` directly. Search does not return full profiles;
  open only those needed for the question, with costly flags off by default.
  PubChem uses `get_ingredient(source: "pubchem", id: "56843331")`; resolve a
  CID with `resolve_identifiers(cid: "56843331")`.
- DSLD product lookups fetch one label by default, retaining its own ingredient
  names, roles, quantities, UNIIs, and row categories/groups.
  `include_ingredient_enrichment: true` adds nutrient CAS/group metadata with up
  to **20 extra serial requests**. `include_ingredients: false` skips DSLD row
  mapping and enrichment even when the enrichment flag is true. Other sources
  still fetch their base record; the tool omits unwanted ingredient output.
- If a returned page or article URL contains needed detail absent from tool
  output, selectively fetch that supplied URL with the host's web tools.
  Do not crawl or walk all pages.

Responses are bounded to 25,000 characters. Search first shortens summaries and
source errors, then removes derived evidence/candidates/links/conflicts, trailing
entities (keeping at least one), trailing records, and finally large identifier
arrays if necessary. A minimal entity shell is the last resort; an unrepresentable
shell returns an explicit tool error, never a false empty successful page.
`truncated` marks output loss; `entitiesOmitted` counts removed entities, and
per-entity `omitted` counts removed summaries, collections, records, identifier
values, and actions. Any loss sets `partial: true`; coverage counts remain
pre-bound. Retained identifiers, URLs, and source+id actions remain exact.

NDC resolution links RxNorm concepts only from NLM package crosswalk evidence,
not openFDA's label-wide RxCUI arrays. Product records still retain those source
arrays. Ingredient UNIIs appear when supplied by the source; default openFDA
directory ingredient rows can lack identifiers. To request SPL label UNIIs,
use `drugdata_resolve_identifiers` with `include_label_ingredients: true`.

For the search design, see
[ADR-0006](docs/decisions/ADR-0006-entity-centric-search.md).

## Historical worked example: aspirin

These calls were run against the live sources on 2026-10-22. Output is
abridged and show the older source-grouped rendering; current searches use
the entity contract above and may already supply the links found in step 2.

**1. Search by name.**

```json
{ "type": "name", "query": "aspirin" }
```

`drugdata_search_ingredients` returns (among others):

```text
### openFDA — 1 result (page 1)
- **ACETYLSALICYLIC ACID** · UNII: R16CO5Y76E · CAS: 50-78-2 · https://api.fda.gov/other/substance.json?search=unii%3A%22R16CO5Y76E%22&limit=1
```

**2. Resolve the UNII.**

```json
{ "unii": "R16CO5Y76E" }
```

`drugdata_resolve_identifiers` returns an ingredient graph:

```text
## Identity — ACETYLSALICYLIC ACID
- Identifiers: UNII: R16CO5Y76E · CAS: 50-78-2 · EC: 200-064-1 · RxCUI: 1191
## Links (3)
- openFDA `R16CO5Y76E` — matched via unii (direct)
- CosIng `100042` — matched via inci (direct)
- RxNorm `1191` — matched via unii (direct)
## Candidates (2)
### DSLD — matched via ingredient-name (name-match)
- Acetylsalicylic acid — https://dsld.od.nih.gov/ingredient/Acetylsalicylic%20acid
### INKEEDecoder — matched via slug (name-match)
- Acetylsalicylic Acid · slug: acetylsalicylic-acid — https://inkeedecoder.com/ingredients/acetylsalicylic-acid
## Confidence
- 3 direct · 0 derived · 2 candidate sets
```

The DSLD and INKEEDecoder entries are deliberately weak, name-based
candidates. The result never promotes them to links.

**3. Fetch the full record from the database that owns it.**

```json
{ "source": "nlm", "id": "1191" }
```

`drugdata_get_ingredient` returns the RxNorm concept `aspirin` (term type
`IN`), its identifiers, an RxTerms presentation block, source link, and next
steps such as opening the CosIng ingredient or resolving a product NDC.

**4. Pull the literature.**

```json
{ "source": "pubmed", "query": "aspirin" }
```

`drugdata_search_references` returns article titles with PMIDs and PubMed
links (ten per page, with a cursor for more). Other reference sources answer
the same shape of question: `clinicaltrials` for studies, `mesh` for
descriptors, `medlineplus` for consumer health topics, `umls` for
Metathesaurus concepts, `rxclass` for drug classes.

## Sourcing and attribution

- **Cite the upstream database, not this server.** Each result names the
  database that supplied it (openFDA, CosIng, RxNorm, RxTerms, RxClass,
  DailyMed, DrugCentral, DSLD, INKEEDecoder, MeSH, PubMed, MedlinePlus, UMLS,
  ClinicalTrials.gov, or PubChem) and includes a deep link.
- **Regulatory and label text is verbatim.** Summarize or quote briefly with
  attribution; do not republish long passages.
- **Do not imply endorsement.** This project is independent and is not
  affiliated with or endorsed by the FDA, the European Commission, NIH, NLM,
  the University of New Mexico, or INKEEDecoder.
- **Respect upstream limits.** No bulk download or mirroring. The server
  honors a one-request-per-second pace for INKEEDecoder, supports optional
  openFDA, DSLD, and PubMed keys, requires a UMLS key for the UMLS reference
  source, and never auto-walks pagination.
- **Keep identifiers intact.** Pass a database's own id back unchanged when
  following a result's `nextSteps`.

Attribution wording, licenses, and per-source caveats are in
[`docs/SOURCES.md`](docs/SOURCES.md).

## Data sources

| Database | Covers | Identifiers |
| --- | --- | --- |
| [openFDA](https://open.fda.gov/) | US drug products, labels, and ingredient substances | NDC, UNII, CAS, SPL set id, application number |
| [CosIng](https://ec.europa.eu/growth/tools-databases/cosing/) | EU cosmetic ingredients, functions, and annex listings | CosIng substance id, INCI name, CAS, EC |
| [RxNorm](https://www.nlm.nih.gov/research/umls/rxnorm/) | Normalized clinical drug concepts and the prescribable name list (NLM) | RxCUI, NDC, UNII |
| [RxTerms](https://www.nlm.nih.gov/research/umls/rxnorm/rxterms.html) | Presentation names for clinical drugs (NLM RxNav) | RxCUI |
| [RxClass](https://www.nlm.nih.gov/research/umls/rxnorm/rxclass.html) | Drug classifications across relationship sources (NLM RxNav) | class id, RxCUI |
| [DailyMed](https://dailymed.nlm.nih.gov/) | Structured Product Label documents (NLM) | SPL set id, NDC, label ingredient UNIIs |
| [DrugCentral](https://drugcentral.org/) | Active-ingredient structures, crosswalks, ATC, clinical assertions, FAERS signals | structId, UNII, RxCUI, CAS, PUBCHEM_CID crosswalk, InChIKey |
| [DSLD](https://dsld.od.nih.gov/) | US dietary supplement labels (NIH ODS) | DSLD label id, barcode, ingredient names, UNIIs, CAS |
| [INKEEDecoder](https://inkeedecoder.com/) | Cosmetic products and ingredient pages | product/ingredient slug, INCI name, CAS, EC |
| [MeSH](https://id.nlm.nih.gov/mesh) | Biomedical subject headings and supplementary concept records (NLM) | MeSH descriptor id |
| [PubMed](https://pubmed.ncbi.nlm.nih.gov/) | Biomedical literature citations (NLM/NCBI) | PMID |
| [MedlinePlus](https://medlineplus.gov/) | Consumer health topics, Genetics pages, Connect drug pages (NLM) | topic/page URL |
| [UMLS](https://uts.nlm.nih.gov/) | Metathesaurus concepts across vocabularies (NLM) | CUI |
| [ClinicalTrials.gov](https://clinicaltrials.gov/) | Registry of clinical studies (NLM) | NCT number |
| [PubChem](https://pubchem.ncbi.nlm.nih.gov/) | Chemical compound records (NCBI) | CID, InChIKey |

Not every source answers every search type. A source that cannot answer is
simply absent from the result; a source that fails contributes an error
status, and the completed entities remain valid. Zero matches are a normal result,
not an error.

## Development

Requirements: Node 22+ (Node 24 LTS recommended), npm, and the repository's
git hooks if you are contributing. See [`AGENTS.md`](AGENTS.md) for the full
setup.

```bash
npm install
npx husky                # .npmrc blocks lifecycle scripts
pre-commit install       # file hygiene + secret scanning
```

| Command | What it does |
| --- | --- |
| `npm run build` | Build the ESM bundle and type declarations. |
| `npm run dev` | Run from source with a watch loop. |
| `npm test` | Run the Vitest suite. |
| `npm run test:coverage` | Run tests with 100% thresholds and LCOV output for Codecov. |
| `npm run typecheck` | Type-check `src/` and `tests/`. |
| `npm run lint` | Biome lint and formatting check. |
| `npm run check` | Biome lint and format, writing changes. |
| `npm run test:smoke` | Inspector CLI `tools/list` against the built server. |
| `npm run inspect` | Open the MCP Inspector against the built server. |

The suite uses an in-process MCP client for tool tests, a spawned stdio test
for the built binary, and fixture-backed HTTP stubs for every source. No test
requires an API key or the network.

### Project layout

```text
src/
  index.ts            stdio entrypoint
  server.ts           createServer(): registrations, fixed order, instructions
  config.ts           lazy environment configuration
  clients.ts          one shared client per source, uniform fetch policy
  sources/
    types.ts          adapter contract and capability declarations
    registry.ts       search fan-out and lookup routing
    openfda.ts        openFDA adapter
    cosing.ts         CosIng adapter
    nlm.ts            RxNorm + DailyMed adapter (with RxTerms profiles)
    nlm-references/   reference search handlers + cursors (one NLM source per call)
    drugcentral.ts    DrugCentral adapter
    dsld.ts           NIH DSLD adapter
    inkeedecoder.ts   INKEEDecoder adapter
    pubchem.ts        PubChem compound adapter (shares the NLM client)
    identity/         two-pass identity chain, SPL parsing, barcode parsing
  tools/              seven tool registrations
  resources/          server://info
  prompts/            research_drug
tests/                fixtures and integration tests
docs/SOURCES.md       source terms, licenses, attribution
docs/decisions/       architecture decision records
```

## Releasing

Published to npm as `@knorby/open-drug-data-mcp` from GitHub Actions with OIDC
trusted publishing — no npm tokens involved. A release is a version bump in a
PR: update `package.json`, `package-lock.json`, `server.json`, and
`CHANGELOG.md` together. Merging an unpublished version publishes the package,
creates the GitHub Release, and publishes the Official MCP Registry record.

See [`docs/publishing-registries.md`](docs/publishing-registries.md) for
registry retry and verification details.

## Documentation

- [`docs/SOURCES.md`](docs/SOURCES.md) — per-database coverage, terms,
  licenses, attribution, and update cadence.
- [`docs/decisions/`](docs/decisions/) — architecture decision records.
- [`docs/publishing-registries.md`](docs/publishing-registries.md) — npm and MCP Registry publishing and retry behavior.
- [`AGENTS.md`](AGENTS.md) — contributor and agent instructions, sourcing
  policy, and release setup.
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — development workflow and commit
  conventions.
- [`skills/open-drug-data/SKILL.md`](https://github.com/knorby/open-drug-data-mcp/blob/main/skills/open-drug-data/SKILL.md) — an
  installable agent skill teaching the search → resolve → get loop.
- [`skills/drug-product-information/SKILL.md`](skills/drug-product-information/SKILL.md) — structured, sourced product reports.
- [`skills/drug-ingredient-information/SKILL.md`](skills/drug-ingredient-information/SKILL.md) — structured, sourced ingredient reports.

## License

[Apache-2.0](LICENSE) © Kali Norby ([@knorby](https://github.com/knorby))

The software license does not relicense any upstream data. Each database keeps
its own terms; see [`docs/SOURCES.md`](docs/SOURCES.md).

TDQS

A4.5/5.0

Scored across 7 tools

Disambiguation4/5

The product vs ingredient tools are clearly separated, and search/get/resolve roles are mostly distinct. There is some overlap around identifiers: an NDC can be used in search_products, get_product, and resolve_identifiers, though the descriptions explain the different purposes. Overall the boundaries are understandable but not perfectly crisp.

Naming Consistency5/5

All tools share a consistent `drugdata_` prefix and follow a predictable verb-plus-resource pattern such as search_products, get_product, and resolve_identifiers. `ping` is the only non-resource verb, but it is conventional and does not disrupt the pattern.

Tool Count5/5

Seven tools is a well-scoped set for a multi-source drug data server, with separate operations for products, ingredients, identifier resolution, references, and health checking. Each tool has a clear place and no bulk of redundant endpoints.

Completeness4/5

The surface covers searching and fetching products and ingredients, cross-source identifier resolution, reference search, and server health. Minor gaps exist in that reference results are link-first rather than retrievable records, and some specialized lookups depend on optional parameters, but core workflows are covered.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues