io.github.SidneyBissoli/medical-terminologies-mcp

Official31 tools

by SidneyBissoli · TypeScript

Medical Terminologies MCP

Diagnoses, drugs & lab codes: ICD-11, SNOMED, LOINC, RxNorm, MeSH, ATC, CID-10. 37 tools, MIT.

Provides access to medical terminology databases including ICD-11, SNOMED, LOINC, and more.

Captured live from the server via tools/list.

icd11_search

Search for medical conditions, diseases, and health problems in ICD-11 (International Classification of Diseases, 11th Revision). Use this tool to: - Find ICD-11 codes for diagnoses - Search for diseases by name or keyword - Look up conditions in multiple languages Returns matching entities with codes, titles, and relevance scores.

Parameters (3)

querystringrequired
Search text (disease name, symptom, or keyword)
languagestring
Language code (default: en)
max_resultsinteger
Maximum number of results (1-100). Default: 25

icd11_lookup

Get detailed information about a specific ICD-11 entity by code or URI. Use this tool to: - Get the full definition of a disease - Retrieve coding notes and exclusions - Get the official title and synonyms Provide either an ICD-11 code (e.g., "BA00") or a full foundation URI.

Parameters (3)

codestring
ICD-11 code (e.g., "BA00", "1A00")
uristring
Full ICD-11 foundation URI
languagestring
Language code (default: en)

icd11_hierarchy

Navigate the ICD-11 hierarchy to find parent or child entities. Use this tool to: - Find broader categories (parents) of a condition - Find specific subtypes (children) of a condition - Understand the classification structure Direction 'parents' returns ancestor categories, 'children' returns subcategories.

Parameters (2)

codestringrequired
ICD-11 code to get hierarchy for
directionstringrequired
Direction: "parents" for ancestors, "children" for subtypes

icd11_chapters

List all ICD-11 chapters (top-level categories). Use this tool to: - Get an overview of ICD-11 structure - Find which chapter covers a body system or condition type - Navigate to specific disease categories ICD-11 has 28 chapters covering all areas of medicine.

Parameters (1)

languagestring
Language code (default: en)

icd11_postcoordination

Get postcoordination information for an ICD-11 code. Use this tool to: - Find available axes for building composite codes - Check required vs optional postcoordination - Understand code extension possibilities Postcoordination allows adding severity, laterality, anatomy, etc.

Parameters (1)

codestringrequired
ICD-11 code to get postcoordination info for

loinc_search

Search for laboratory tests, clinical observations, and measurements in LOINC (Logical Observation Identifiers Names and Codes). Use this tool to: - Find LOINC codes for lab tests (e.g., "glucose", "hemoglobin") - Search for clinical measurements and vital signs - Look up diagnostic observations Returns matching LOINC codes with names, components, and properties.

Parameters (2)

querystringrequired
Search term (test name, keyword, or partial LOINC code)
max_resultsinteger
Maximum number of results (1-100). Default: 25

loinc_details

Get detailed information about a specific LOINC code. Use this tool to: - Get the full name and description of a LOINC code - Find the component, property, timing, and system - Check the scale type and method Provide a LOINC number in format "XXXXX-X" (e.g., "2339-0" for Glucose).

Parameters (1)

loinc_numstringrequired
LOINC number (e.g., "2339-0")

loinc_answers

Get the list of valid answers for a LOINC questionnaire item. Use this tool to: - Find valid response options for survey questions - Get answer codes for data entry validation - Look up standardized answer lists Only applicable to LOINC codes that represent questions with defined answer sets.

Parameters (1)

loinc_numstringrequired
LOINC number (e.g., "2339-0")

loinc_panels

Get the structure of a LOINC panel or form. Use this tool to: - See all tests included in a panel (e.g., CBC, metabolic panel) - Get the structure of assessment forms - Find related observations grouped together Returns the list of LOINC codes that make up the panel.

Parameters (1)

loinc_numstringrequired
LOINC number (e.g., "2339-0")

rxnorm_search

Search for drugs in RxNorm (Normalized names for clinical drugs). Use this tool to: - Find drug concepts by brand or generic name - Look up medications for prescribing - Search for drug formulations Returns matching drugs with RxCUI identifiers, names, and term types.

Parameters (2)

querystringrequired
Drug name to search (brand or generic)
max_resultsinteger
Maximum number of results (1-100). Default: 25

rxnorm_concept

Get detailed information about a specific RxNorm concept by RxCUI. Use this tool to: - Get the full name and synonyms for a drug - Check the concept status (active, remapped, etc.) - View related concepts (ingredients, brands, forms) Provide an RxCUI (RxNorm Concept Unique Identifier) like "161".

Parameters (2)

rxcuistringrequired
RxNorm Concept Unique Identifier
include_relatedboolean
Include related concepts (ingredients, brands, dose forms)

rxnorm_ingredients

Get active ingredients for a drug by RxCUI. Use this tool to: - Find the active ingredients in a medication - Check for single vs. multiple ingredient products - Identify the generic components of brand drugs Returns ingredient RxCUIs and names.

Parameters (1)

rxcuistringrequired
RxCUI of the drug

rxnorm_classes

Get therapeutic and pharmacologic classes for a drug. Use this tool to: - Find the drug class (e.g., "Beta-blockers", "NSAIDs") - Identify therapeutic categories - Look up mechanism of action classifications Returns class IDs, names, and classification sources.

Parameters (1)

rxcuistringrequired
RxCUI of the drug

rxnorm_ndc

Map between RxNorm concepts and National Drug Codes (NDC). Use this tool to: - Get all NDC codes for a drug (by RxCUI) - Find the RxCUI for an NDC code - Cross-reference between coding systems Provide either an RxCUI to get NDCs, or an NDC to get the RxCUI.

Parameters (2)

rxcuistring
RxCUI to get NDC codes for
ndcstring
NDC code to look up RxCUI (alternative to rxcui)

mesh_search

Search for MeSH (Medical Subject Headings) descriptors. Use this tool to: - Find MeSH terms for indexing medical literature - Look up subject headings for PubMed searches - Find controlled vocabulary terms Returns matching descriptors with MeSH IDs and labels.

Parameters (4)

querystringrequired
Search term (e.g., "diabetes", "heart failure")
matchstring
Match type: exact, contains, or startswith. Default: contains
languagestring
Language code (default: en)
max_resultsinteger
Maximum number of results (1-100). Default: 25

mesh_descriptor

Get detailed information about a MeSH descriptor by ID. Use this tool to: - Get the full definition (scope note) of a MeSH term - View tree numbers showing hierarchy location - See related concepts and synonyms Provide a MeSH Descriptor ID like "D015242" (Ofloxacin).

Parameters (2)

mesh_idstringrequired
MeSH Descriptor ID (e.g., D015242, D003920)
languagestring
Language code (default: en)

mesh_tree

Get the tree hierarchy location(s) for a MeSH descriptor. Use this tool to: - See where a term fits in the MeSH hierarchy - Understand broader/narrower relationships - Find related terms in the same branch MeSH tree numbers show the hierarchical path (e.g., C14.280.647 for Myocardial Infarction).

Parameters (1)

mesh_idstringrequired
MeSH Descriptor ID (e.g., D015242, D003920)

mesh_qualifiers

Get allowed qualifiers (subheadings) for a MeSH descriptor. Use this tool to: - Find which qualifiers can be combined with a descriptor - Build precise MeSH search queries - Understand aspects that can be specified Qualifiers refine descriptors (e.g., "Diabetes Mellitus/drug therapy").

Parameters (1)

mesh_idstringrequired
MeSH Descriptor ID (e.g., D015242, D003920)

map_icd10_to_icd11

Authoritative ICD-10 → ICD-11 mapping using WHO transition tables (release 2025-01, bundled with the server). Returns the primary 1:1 ICD-11 category for the ICD-10 code plus any alternative ICD-11 candidates that WHO documents (some ICD-10 concepts split into multiple ICD-11 entities). For each mapping, includes the ICD-11 code, title, chapter, and the Foundation URI / Linearization URI for navigating to the full entity definition. Use this for clinical coding, billing migration, retrospective analysis, and any workflow that needs authoritative mapping rather than text-search candidates. Coverage: 11,243 ICD-10 categories (excludes chapters and blocks like "A00-A09" which aren't used in clinical coding). Provide a code like "E11" (Type 2 diabetes), "I21" (Acute MI), or "A07.8" (4 alternatives in WHO's table). Both dotted ("A07.8") and undotted ("A078") forms are accepted. Returns "no mapping" when the code isn't in the WHO category-level table — that's the honest answer rather than a fuzzy search fallback.

Parameters (1)

icd10_codestringrequired
ICD-10 code to query in the ICD-11 search index (e.g., E11, I21.0, J18.9)

map_loinc_to_snomed

This tool looks up a LOINC code in NLM Clinical Tables and returns guidance on where to obtain a LOINC → SNOMED CT mapping. It does not perform the mapping. Direct LOINC → SNOMED CT mappings are not freely available via API. UMLS Metathesaurus contains the relationships but requires an individual UMLS Terminology Services license; the LOINC SNOMED CT Expression Association is published by Regenstrief Institute as part of the LOINC release and requires authenticated download from loinc.org under the LOINC license. For programmatic LOINC → SNOMED mapping, use UMLS or the LOINC Expression Association files. For interactive lookup, use the SNOMED CT browser available to your organization or the Regenstrief RELMA desktop tool. Provide a LOINC code like "2339-0" (Glucose) or "718-7" (Hemoglobin).

Parameters (1)

loinc_codestringrequired
LOINC code (e.g., 2339-0 for Glucose)

validate_codes

Validate a mixed batch of medical codes against their source terminologies. Useful for retrospective analysis of legacy databases — flag codes that no longer exist, surface ICD-10 → ICD-11 replacements, and grade activity status where the terminology exposes it. For each input `{ code, terminology }`, returns: - **valid**: whether the code exists in the source terminology. - **active**: whether the code is currently active. Null when the source doesn't expose an explicit active/inactive distinction at category level (CID-10, ATC, ICD-11, RxNorm, MeSH all return null today; SNOMED and LOINC return a real boolean). - **title**: the official label/name when available. - **replaced_by**: a successor code, populated today only for ICD-10 codes that have a primary ICD-11 mapping in the bundled WHO transition tables. - **source**: human-readable provenance of the validation (terminology + release/version). - **error**: non-null only when validation couldn't be performed (network error, SNOMED feature flag off, etc.). `valid: false` + `error: null` means "code not found"; `valid: false` + `error: set` means "couldn't validate". Terminology is **required per code** — auto-detection isn't supported because category codes like "A00" exist in both ICD-10 and CID-10. Accepted values: `icd11`, `icd10`, `snomed`, `loinc`, `rxnorm`, `mesh`, `atc`, `cid10`. Hard cap of 50 codes per call; codes are validated in parallel through their respective clients, so total wall time scales with the slowest upstream + its rate limit (worst case ~10 s for a full batch hitting ICD-11).

Parameters (1)

codesarrayrequired
List of code+terminology pairs to validate. Hard cap of 50 per call to keep total latency under ~10 s given upstream rate limits.

find_equivalent

Search for equivalent terms across multiple medical terminologies. Use this tool to: - Find the same concept in different coding systems - Compare how terminologies represent a concept - Support terminology mapping and data integration Searches across: ICD-11, SNOMED CT, LOINC, RxNorm, and MeSH. Set `target_terminologies` to limit which are searched, or set `source_terminology` to exclude one (e.g. when you already have a code from that terminology and want equivalents elsewhere). The two combine: source is subtracted from targets.

Parameters (3)

termstringrequired
Medical term to search (e.g., "diabetes", "aspirin")
source_terminologystring
If set, this terminology is excluded from the search. Use this when the term came from this terminology and you want equivalents in the others. Combines with target_terminologies by subtraction (source is removed from the target list).
target_terminologiesarray
Limit the search to these terminologies. If omitted, all five are searched.

atc_classify

Look up the WHO ATC (Anatomical Therapeutic Chemical) classification(s) for a drug by name. Use this tool to: - Find the ATC code for a medication (e.g., "metformin" → A10BA02) - Identify the therapeutic and pharmacological class hierarchy - Cross-reference drugs with their international ATC codes Returns one entry per ATC code the drug belongs to. A single-ingredient drug typically maps to one substance-level code; combination products map to multiple. ATC codes are international (WHO Collaborating Centre); this tool retrieves them via NLM RxClass.

Parameters (1)

drug_namestringrequired
Drug name to classify (brand or generic, e.g., "metformin")

atc_lookup

Look up an ATC code at level 1-4 to get its name and hierarchy level. Use this tool to: - Resolve an ATC code (e.g., "A10BA") to its class name ("Biguanides") - Confirm a code exists in the current ATC index - Identify the level (anatomical / therapeutic / pharmacological / chemical) Accepts codes 1-5 characters long: "A" (anatomical), "A10" (therapeutic), "A10B" (pharmacological), "A10BA" (chemical). Substance-level codes (7 chars, e.g., "A10BA02") are not exposed by this endpoint — use atc_classify with the drug name to retrieve the substance code.

Parameters (1)

atc_codestringrequired
ATC code at level 1-4 (1-5 chars). Substance-level codes (7 chars, e.g., A10BA02) are not exposed by this endpoint — use atc_classify with the drug name instead.

atc_members

List the drugs (substances) that belong to an ATC class. Use this tool to: - Enumerate all members of a therapeutic class (e.g., "A10BA" → metformin, phenformin) - Build a list of drugs sharing a pharmacological mechanism - Explore an ATC subtree at any level Each member includes its substance-level (7-char) ATC code via source_atc_code, useful for disambiguation when the queried class is at level 1-4. RxNorm's catalog is US-centric; the ATC class names and codes themselves are international.

Parameters (1)

atc_codestringrequired
ATC code at any level. Higher levels (1-4) return all member substances; level 5 returns the single substance.

cid10_search

Search the Brazilian CID-10 (Classificação Estatística Internacional de Doenças, 10ª Revisão) by Portuguese text. Use this tool to: - Find CID-10 codes for Brazilian SUS / ANVISA contexts ("infarto", "diabetes", "tuberculose") - Look up the official Portuguese (CBCD/USP) translation of a clinical term - Locate codes for billing, epidemiology, and clinical documentation in Brazil Returns matches from CID-10 categories (3-char) and/or subcategories (4-char). Search is diacritic-insensitive: typing "infeccoes" matches "infecções". This tool searches the Brazilian Portuguese CID-10 V2008 — for the international ICD-11 (current WHO revision, in English by default), use icd11_search.

Parameters (3)

querystringrequired
Search term in Portuguese (e.g., "diabetes", "infarto", "tuberculose")
levelstring
Restrict search to 3-char categories, 4-char subcategories, or both. Default: all
max_resultsinteger
Maximum number of results (1-100). Default: 25

cid10_lookup

Look up a specific CID-10 code and return its Portuguese name. Use this tool to: - Resolve a code to its Brazilian description ("I21" → "Infarto agudo do miocárdio") - Confirm a 3-char category or 4-char subcategory exists in CID-10 - Retrieve gender / cause-of-death restriction flags when applicable Accepts both dotted ("A00.1") and undotted ("A001") forms; returns the canonical display.

Parameters (1)

codestringrequired
CID-10 code (e.g., "A00", "A00.1", "A001", "I21"). Dotted and undotted forms both accepted.

cid10_chapters

List the 22 chapters of CID-10 with their code ranges and Portuguese titles. Use this tool to: - See the top-level structure of CID-10 (chapters I-XXII, e.g., "I. Algumas doenças infecciosas e parasitárias", "IX. Doenças do aparelho circulatório") - Map a code to its chapter by code range (e.g., I00-I99 → chapter IX) - Build a navigable table of contents for downstream tooling Returns 22 entries — CID-10 V2008 has not been updated since 2008.

No parameters.

cid10_chapter

Get one CID-10 chapter and its constituent groups (e.g., "Chapter IX → I00-I02 Febre reumática aguda, I05-I09 Doenças reumáticas crônicas do coração, ..."). Use this tool to: - Drill from a chapter into its groups - Build hierarchical browsers - Find which group contains a code range Provide a chapter number (1-22).

Parameters (1)

numintegerrequired
Chapter number (1-22). CID-10 V2008 has 22 chapters.

terminology_versions

List the current version, release date, publisher, source URL, and update cadence of every terminology this server queries against. Useful for pipeline maintainers who need to: - Confirm which release of ICD-11 / SNOMED / LOINC / RxNorm / MeSH / ATC the server is querying before a batch run. - Verify the bundled CID-10 (frozen at V2008) and ICD-10 → ICD-11 transition tables (currently 2025-01) match expectations. - Cite the data version in research artifacts. Pass `terminology` to filter to a single entry; otherwise the full set of 8 is returned. The ICD-10 → ICD-11 version reads live from the bundled dataset; everything else is metadata maintained alongside the project release.

Parameters (1)

terminologystring
Filter to a single terminology. Omit to return all 8.

terminology_diff

Report what diff data is available between two versions of a terminology. For most terminologies this is **guidance only** — the server doesn't ship historical snapshots, so the tool points at the publisher's official changelog and explains the cadence. `bundled_versions` lists the version(s) this server actually has on hand. For **ICD-10 vs ICD-11** specifically, the tool surfaces a real cross-revision summary from the bundled WHO transition tables (the ICD-10 → ICD-11 case is a structural diff between two WHO revisions). Use `terminology: "icd10"` with no `to_version` to get the cross-revision summary: total mapped ICD-10 categories, how many are 1:1 vs split into multiple ICD-11 codes, and the average number of alternatives when split. Inputs: - `terminology` (required): which terminology to report on. - `from_version` (optional): the version you have data from. If omitted, the tool reports against the currently-bundled version. - `to_version` (optional): the version you want to compare to. If omitted, the tool reports against the publisher's latest known release. This tool is intentionally a metadata + guidance layer, not a diff engine — for terminologies that change frequently (SNOMED, LOINC, RxNorm, MeSH), the publisher's official changelog is the authoritative source.

Parameters (3)

terminologystringrequired
Which terminology to report on.
from_versionstring
Version you have data from. Optional; behavior depends on terminology.
to_versionstring
Version you want to compare to. Optional.

README.md25 KBView on GitHub

Medical Terminologies MCP Server

A Model Context Protocol (MCP) server providing unified access to major global medical terminologies:

ICD-11 - International Classification of Diseases (WHO)
SNOMED CT - Systematized Nomenclature of Medicine (opt-in; requires self-hosted Snowstorm)
LOINC - Logical Observation Identifiers Names and Codes
RxNorm - Normalized names for clinical drugs (NIH)
MeSH - Medical Subject Headings (NLM)
ATC - Anatomical Therapeutic Chemical classification (WHO Collaborating Centre, served via NLM RxClass)
CID-10 - Brazilian Portuguese translation of ICD-10 (DataSUS V2008, bundled)

See it in action

Ask your assistant:

"What's the ICD-11 code for type 2 diabetes?" → icd11_search
"Map ICD-10 code E11 to ICD-11." → map_icd10_to_icd11
"What does LOINC 2339-0 measure?" → loinc_details
"Qual o código CID-10 para infarto agudo do miocárdio?" → cid10_search

The answers come from authoritative sources (WHO, NLM, NIH, DataSUS) — real codes and mappings, not guesses from training data.

Features

31 default tools (37 with SNOMED enabled) for medical terminology lookup
3 MCP Prompts that orchestrate tool calls into named workflows (find-medical-code, drug-info, cid10-portuguese-lookup) — clients render these as one-click user actions
4 MCP Resources for in-process reference content (info://server, info://cid10/chapters, info://licenses, info://stats) — sub-millisecond reads (except info://stats which round-trips to the StatsCounter Durable Object on the hosted endpoint)
Multi-terminology support in a single server
Cross-terminology mapping and search
Built-in caching for improved performance
Rate limiting to respect API limits
Detailed responses with rich formatting
Two transports: stdio (default; for Claude Desktop, IDE clients) and Streamable HTTP (for hosted deployments — runs on Cloudflare Workers at the edge by default, Smithery URL submission, or self-hosted Docker)

Who is this for?

This server is not a clinical-care decision tool — practicing clinicians have specialized assistants (UpToDate AI, OpenEvidence, EHR-integrated tools) for that. The actual audience is researchers, public-health analysts, clinical informatics developers, and educators who need programmatic access to authoritative terminology data.

If you're a...	Start with	Why
Biomedical researcher / bibliographer	`mesh_search`, `mesh_descriptor`, `mesh_tree`	MeSH is PubMed's indexing vocabulary; tree numbers let you traverse the controlled hierarchy programmatically
Public-health analyst (Brazil / SUS)	`cid10_search`, `cid10_chapters`, `atc_classify`	CID-10 V2008 is the Brazilian operational standard; ATC pairs cleanly with DataSUS prescription data
Public-health analyst (international)	`icd11_search`, `icd11_lookup`, `icd11_chapters`	WHO ICD-11 is the current international revision; chapters and hierarchy support pipeline classification
Clinical-informatics developer	`loinc_search`, `loinc_details`, `find_equivalent`	LOINC for lab/observation interoperability; cross-terminology search to scaffold new mappings
Educator / curriculum author	`mesh_descriptor`, `icd11_lookup`, `rxnorm_search`	Authoritative definitions, tree numbers, and drug term-types you can drop into self-checked exercises

Try the hosted instance (no install)

A public Cloudflare Workers deployment runs at:

code

https://medical.sidneybissoli.com/mcp

Connect via the MCP Inspector or any Streamable HTTP MCP client:

bash

npx @modelcontextprotocol/inspector --transport streamable-http \
  --server-url https://medical.sidneybissoli.com/mcp

Or install via Smithery, which proxies the same endpoint through their gateway:

bash

npx -y smithery mcp add sidneybissoli/medical-terminologies-mcp

The hosted instance has WHO credentials configured, so all 31 default tools work without any setup on your side. For your own deployment (e.g. corporate network, different region, custom WHO credentials), see the Installation and Hosted on Cloudflare Workers sections below.

Installation

Global Installation (Recommended)

bash

npm install -g medical-terminologies-mcp

Local Installation

bash

npm install medical-terminologies-mcp

Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

json

{
  "mcpServers": {
    "medical-terminologies": {
      "command": "npx",
      "args": ["-y", "medical-terminologies-mcp"],
      "env": {
        "WHO_CLIENT_ID": "your-who-client-id",
        "WHO_CLIENT_SECRET": "your-who-client-secret"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
`WHO_CLIENT_ID`	Yes¹	WHO ICD API Client ID
`WHO_CLIENT_SECRET`	Yes¹	WHO ICD API Client Secret
`WHO_ICD11_RELEASE_ID`	No	ICD-11 release to query (e.g. `2024-01`, `2025-01`). Default `2024-01`.
`ENABLE_SNOMED_TOOLS`	No²	Set to `true` to register the 6 SNOMED-dependent tools. Default off.
`SNOMED_BASE_URL`	No²	Base URL for a Snowstorm instance, e.g. `https://my-snowstorm.example.com/snowstorm/snomed-ct`.
`SNOMED_LANGUAGE`	No²	Accept-Language tag(s) for SNOMED responses, e.g. `pt`, `pt-BR`, `es`. Default `en`. Single-tag values are pass-through reliably; composite values with q-weights (e.g. `pt-BR,en;q=0.8`) depend on your Snowstorm instance's Accept-Language handling — fallback semantics may vary. Test against your specific deployment if relying on weighted fallback.
`LOG_LEVEL`	No	pino log level (`debug`, `info`, `warn`, `error`, `fatal`). Default `info`.

¹ Required for ICD-11 tools. Get credentials at: https://icd.who.int/icdapi.

² See SNOMED CT setup (advanced) below. LOINC, RxNorm, and MeSH need no configuration.

HTTP transport (hosted / shared deployments)

The server runs over stdio by default — that's what Claude Desktop and IDE clients expect. For hosted deployments (Cloudflare Workers, Smithery, your own Docker container), pass --http to switch to Streamable HTTP transport instead:

bash

medical-terminologies-mcp --http --port 3000
# or, in Docker / containers:
medical-terminologies-mcp --http --host 0.0.0.0 --port 3000

Flag	Env var	Default	Description
`--http`	`MCP_HTTP=true`	off	Enable Streamable HTTP transport instead of stdio
`--port N`	`PORT`	`3000`	TCP port to listen on (use `0` for an ephemeral port)
`--host H`	`HOST`	`127.0.0.1`	Bind address. Pass `0.0.0.0` for container/hosted use

Endpoints:

POST /mcp — JSON-RPC over Streamable HTTP (the MCP protocol). Stateless mode: each request is independent, no session cookies.
GET /health — liveness probe returning { status, name, version, tool_count } for load balancers and uptime monitors.
CORS is permissive (*) so browser clients (e.g. the MCP Inspector web UI) can connect directly.

Quick smoke test from another terminal:

bash

curl -sS http://localhost:3000/health
# {"status":"ok","name":"medical-terminologies-mcp","version":"1.5.0","tool_count":31}

# Inspector via HTTP
npx @modelcontextprotocol/inspector --transport streamable-http --server-url http://localhost:3000/mcp

Hosted on Cloudflare Workers (primary)

The production deployment is a Cloudflare Worker. Source lives in src/worker.ts, config in wrangler.toml, and CI deploy in .github/workflows/deploy-worker.yml (auto-runs on every push to main).

To deploy your own instance:

bash

npm ci
npm run build:worker
npx wrangler login         # one-time, browser flow
npx wrangler deploy        # publishes to <name>.<account>.workers.dev
# Set ICD-11 secrets so those 5 tools work:
npx wrangler secret put WHO_CLIENT_ID
npx wrangler secret put WHO_CLIENT_SECRET

The public endpoint is POST https://<name>.<account>.workers.dev/mcp. CORS is permissive so the MCP Inspector web UI connects directly. /health returns { status, name, version, tool_count, uptime_s }.

Why Workers: zero cold start at the edge, $5/mo flat for 10M requests (free tier covers up to 100k req/day), and no VMs to size or restart. Stage-1 deploy uses per-isolate cache + rate-limiter — fine for moderate traffic; under sustained high load, swap in Workers KV cache and a Durable Object rate limiter (tracked as PROGRESS.md Phase 11.9 Stage 2 follow-up).

Listing on Smithery

After your Worker is live, register the URL on Smithery:

Visit https://smithery.ai → Publish → MCP (or https://smithery.ai/new).
Pick the URL submission path (Smithery deprecated container hosting in 2024 — URL is the supported flow now).
Paste https://<your-worker>.workers.dev/mcp. Smithery's gateway scans for compliance and proxies traffic.

Self-hosted Docker (alternative)

If you'd rather run the server in your own infrastructure (private deployment, internal compliance constraints, on-prem), the repo includes a Dockerfile:

bash

docker build -t medical-terminologies-mcp .
docker run --rm -p 3000:3000 \
  -e PORT=3000 \
  -e WHO_CLIENT_ID=... -e WHO_CLIENT_SECRET=... \
  medical-terminologies-mcp

Multi-stage build (~150 MB), runs node dist/index.js --http, binds 0.0.0.0:$PORT. Same MCP endpoints as the Workers deployment.

Available Tools (31 by default, 37 with SNOMED enabled)

ICD-11 Tools (5)

Tool	Description	Example
`icd11_search`	Search ICD-11 by term	`query: "diabetes mellitus"`
`icd11_lookup`	Get entity details by code/URI	`code: "5A11"`
`icd11_hierarchy`	Navigate parent/child relationships	`code: "5A11"`
`icd11_chapters`	List all ICD-11 chapters	-
`icd11_postcoordination`	Get postcoordination axes	`code: "5A11"`

LOINC Tools (4)

Tool	Description	Example
`loinc_search`	Search lab tests and observations	`query: "glucose"`
`loinc_details`	Get full LOINC code details	`loinc_num: "2339-0"`
`loinc_answers`	Get answer list for surveys	`loinc_num: "44249-1"`
`loinc_panels`	Get panel/form structure	`loinc_num: "24331-1"`

RxNorm Tools (5)

Tool	Description	Example
`rxnorm_search`	Search drugs by name	`query: "metformin"`
`rxnorm_concept`	Get drug concept details	`rxcui: "6809"`
`rxnorm_ingredients`	Get active ingredients	`rxcui: "6809"`
`rxnorm_classes`	Get therapeutic classes	`rxcui: "6809"`
`rxnorm_ndc`	Map between RxCUI and NDC	`rxcui: "6809"`

MeSH Tools (4)

Tool	Description	Example
`mesh_search`	Search MeSH descriptors	`query: "hypertension"`
`mesh_descriptor`	Get descriptor details	`mesh_id: "D006973"`
`mesh_tree`	Get tree hierarchy location	`mesh_id: "D006973"`
`mesh_qualifiers`	Get allowed qualifiers	`mesh_id: "D006973"`

SNOMED CT Tools (5, disabled by default)

These are only registered when ENABLE_SNOMED_TOOLS=true. See SNOMED CT setup (advanced).

Tool	Description	Example
`snomed_search`	Search concepts by term	`query: "myocardial infarction"`
`snomed_concept`	Get concept details by SCTID	`sctid: "22298006"`
`snomed_hierarchy`	Get parent/child concepts	`sctid: "22298006"`
`snomed_descriptions`	Get all descriptions	`sctid: "22298006"`
`snomed_ecl`	Execute ECL queries	`ecl: "<< 73211009"`

Crosswalk Tools (5 — `map_snomed_to_icd10` requires SNOMED)

Tool	Description	Example
`map_icd10_to_icd11`	Authoritative ICD-10 → ICD-11 mapping via bundled WHO transition tables; returns primary code + chapter + URIs and any WHO-documented alternatives	`icd10_code: "E11"`
`map_snomed_to_icd10`	SNOMED CT → ICD-10 guidance (only when `ENABLE_SNOMED_TOOLS=true`)	`sctid: "73211009"`
`map_loinc_to_snomed`	LOINC ↔ SNOMED guidance	`loinc_code: "2339-0"`
`validate_codes`	Batch-validate up to 100 codes across ICD-11, LOINC, RxNorm, MeSH, ATC, CID-10 (and SNOMED when enabled); returns per-code valid/invalid + display name	`codes: [{terminology:"icd11",code:"5A11"}, …]`
`find_equivalent`	Cross-terminology search; SNOMED branch is skipped when SNOMED tools are disabled	`term: "diabetes"`

ATC Tools (3)

WHO Anatomical Therapeutic Chemical classification, served through NLM RxClass (free, no auth). The WHOCC base itself requires a paid subscription, but RxClass envelopes the same code/name pairs.

Tool	Description	Example
`atc_classify`	Drug name → ATC code(s)	`drug_name: "metformin"`
`atc_lookup`	ATC code (level 1-4) → name + level type	`atc_code: "A10BA"`
`atc_members`	ATC class → member drugs	`atc_code: "A10BA"`

CID-10 Tools (4)

Brazilian Portuguese translation of ICD-10 (DataSUS V2008). Bundled as a static dataset — no HTTP calls. The Brazilian SUS uses CID-10 V2008 operationally; for the international ICD-11 (current WHO revision), use the ICD-11 tools above.

Tool	Description	Example
`cid10_search`	Portuguese text search (diacritic-insensitive)	`query: "diabetes"`
`cid10_lookup`	Code → official Portuguese name	`code: "I21"` or `"A00.1"`
`cid10_chapters`	List the 22 CID-10 chapters	-
`cid10_chapter`	Chapter detail with constituent groups	`num: 9`

Versioning Tools (2)

Surface what version of each terminology this server queries against today — useful when running batch validation against a pinned release or when investigating an unexpected lookup miss after an upstream update.

Tool	Description	Example
`terminology_versions`	List all 8 supported terminologies with current version, release date, publisher, source URL, and update cadence	-
`terminology_diff`	Report what diff data is available between two versions of a terminology (real cross-revision stats for ICD-10 → ICD-11; guidance otherwise)	`terminology: "icd10-icd11"`

Example Outputs

The samples below are the actual formatted output the tools produce — the text body of the CallToolResult. Tools also return a structuredContent object matching each tool's outputSchema for programmatic consumers.

`loinc_search` — query: "glucose", max_results: 3

markdown

## LOINC Search Results for "glucose"

Found 1024 total results (showing 3):

1. **74790-7** - Glucose challenge (hydrogen breath test) panel - Exhaled gas
   Component: Glucose challenge panel | Method: -

2. **104708-3** - Deprecated Estimated average glucose [Moles/volume] in Blood
   Component: Estimated average glucose | Property: SCnc

3. **97510-2** - Glucose measurements in range out of Total glucose measurements during reporting period
   Component: Glucose measurements in range/Total glucose measurements | Property: NFr | Method: Calculated

total_count (1024) reflects every match in the NLM Clinical Tables index, not just the page returned. Bump max_results (max 50) to see canonical codes like 2339-0 (Glucose [Mass/volume] in Blood); the API's relevance ranking puts panels and derived measurements above plain blood-glucose at small page sizes.

`rxnorm_ingredients` — rxcui: "6809" (metformin)

markdown

# Ingredients for RxCUI 6809

Found 18 ingredient(s):

| RxCUI | Name | Type |
|-------|------|------|
| 6809 | metformin | Single Ingredient |
| 1007411 | chlorpropamide / metformin | Multiple Ingredient |
| 1043562 | metformin / saxagliptin | Multiple Ingredient |
| 1243019 | linagliptin / metformin | Multiple Ingredient |
| 1486436 | dapagliflozin / metformin | Multiple Ingredient |
| 1545149 | canagliflozin / metformin | Multiple Ingredient |
| 1664314 | empagliflozin / metformin | Multiple Ingredient |
| 729717  | metformin / sitagliptin | Multiple Ingredient |
| ...     | (10 more combinations)   | Multiple Ingredient |

For an RxCUI that is itself an ingredient (TTY=IN), the tool returns that ingredient plus every multi-ingredient (TTY=MIN) concept that includes it. Use this to enumerate combination products built around a substance.

`mesh_descriptor` — mesh_id: "D006973" (Hypertension)

markdown

# Hypertension
MeSH ID: D006973

## Scope Note

Persistently high systemic arterial BLOOD PRESSURE. Based on multiple readings (BLOOD PRESSURE DETERMINATION), hypertension is currently defined as when SYSTOLIC PRESSURE is consistently greater than 140 mm Hg or when DIASTOLIC PRESSURE is consistently 90 mm Hg or more.

## Tree Numbers

- C14.907.489

## Concepts

- Hypertension *(preferred)*

## Allowed Qualifiers

35 qualifier(s) allowed. Use mesh_qualifiers for details.

The scope note comes from the descriptor's preferred concept, not its annotation field (which is an indexer-facing note). Tree numbers are the navigable path into MeSH's controlled hierarchy — C14.907.489 places Hypertension under Cardiovascular Diseases → Vascular Diseases.

Common Workflows

ICD-11 lookup: icd11_search with a clinical term → pick the result → icd11_lookup with the code for full details, or icd11_hierarchy to walk parents/children.
Drug pipeline: rxnorm_search for a brand or generic name → rxnorm_concept for the canonical record → rxnorm_ingredients and rxnorm_classes for downstream analysis.
Cross-terminology scaffolding: find_equivalent with a clinical term searches ICD-11, LOINC, RxNorm, MeSH, and (when enabled) SNOMED in one call. Use it to bootstrap mappings; the pairwise map_* tools refine them.
ICD-10 → ICD-11 (text search, not authoritative): map_icd10_to_icd11 does honest text search against WHO ICD-11. Real WHO transition tables are tracked in PROGRESS.md Phase 13.1.

SNOMED CT setup (advanced)

The 5 SNOMED tools (snomed_search, snomed_concept, snomed_hierarchy, snomed_descriptions, snomed_ecl) plus the SNOMED-dependent crosswalk tool (map_snomed_to_icd10) are disabled by default. With them disabled, the server registers 31 tools instead of 37; find_equivalent still works and skips the SNOMED branch with an explanatory note.

The reason: as of 2026-05-08, the public IHTSDO Snowstorm endpoint that this project historically called (https://browser.ihtsdotools.org/snowstorm/snomed-ct/...) returns HTTP 410 Gone for every path. Without a working backend, registering these tools surfaces 6 guaranteed-broken tools to every client.

To enable the SNOMED tools:

Confirm your SNOMED CT license. SNOMED CT use requires an SNOMED International (IHTSDO) license. Member country residents typically have one through their national release center; non-members can obtain an Affiliate license. See https://www.snomed.org/snomed-ct/get-snomed.
Run a Snowstorm instance. SNOMED International publishes Snowstorm as open source (IHTSDO/snowstorm) and as a Docker image (snomedinternational/snowstorm). Self-hosting requires importing an RF2 release file (provided to license holders).

Configure this server:

json

{
  "mcpServers": {
    "medical-terminologies": {
      "command": "npx",
      "args": ["-y", "medical-terminologies-mcp"],
      "env": {
        "WHO_CLIENT_ID": "...",
        "WHO_CLIENT_SECRET": "...",
        "ENABLE_SNOMED_TOOLS": "true",
        "SNOMED_BASE_URL": "https://my-snowstorm.example.com/snowstorm/snomed-ct",
        "SNOMED_LANGUAGE": "en"
      }
    }
  }
}

SNOMED_BASE_URL should point at the base under which Snowstorm exposes its /MAIN/concepts and related endpoints. SNOMED_LANGUAGE accepts standard Accept-Language tags (e.g. pt, es, pt-BR,en;q=0.8) — Snowstorm returns localized terms when the branch has them and falls back to English otherwise.

Restart the MCP client so the server picks up the env vars.

If you set ENABLE_SNOMED_TOOLS=true without configuring a working Snowstorm, the SNOMED tools will register but every call will fail at the network layer.

Terminology Licenses

ICD-11 (WHO)

ICD-11 content is provided under the Creative Commons Attribution-NoDerivatives 3.0 IGO license (CC BY-ND 3.0 IGO).

You must attribute WHO as the source
You may not create derivative works
API access requires registration at https://icd.who.int/icdapi

SNOMED CT

SNOMED CT use requires an IHTSDO (SNOMED International) license. The SNOMED tools in this server are disabled by default and only enabled by operators with a valid license and a self-hosted Snowstorm instance — see SNOMED CT setup (advanced).

Member countries have national licenses
Affiliate licenses available for others
More info: https://www.snomed.org/snomed-ct/get-snomed

LOINC

LOINC content is provided under the LOINC License.

Free for most uses
Attribution required
Registration recommended

RxNorm

RxNorm is produced by the U.S. National Library of Medicine and is freely available.

No license required for use
Attribution appreciated

MeSH

MeSH is produced by the U.S. National Library of Medicine and is freely available.

No license required for use
Attribution appreciated

API Rate Limits

This server implements rate limiting to respect API providers:

API	Rate Limit
WHO ICD-11	5 requests/second
NLM (LOINC, MeSH)	10 requests/second
RxNorm	20 requests/second
SNOMED CT (Snowstorm)	10 requests/second

Development

Building from source

bash

git clone https://github.com/SidneyBissoli/medical-terminologies-mcp.git
cd medical-terminologies-mcp
npm install
npm run build

Running locally

bash

npm start

Testing with MCP Inspector

bash

npx @modelcontextprotocol/inspector node dist/index.js

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Author

Sidney Bissoli

GitHub: @SidneyBissoli

License

This project is licensed under the MIT License - see the LICENSE file for details.

Note: While this software is MIT licensed, the medical terminologies accessed through it have their own licenses (see Terminology Licenses above).

Acknowledgments

WHO for the ICD-11 API
Regenstrief Institute for LOINC
U.S. National Library of Medicine for RxNorm and MeSH
SNOMED International for SNOMED CT
Anthropic for the Model Context Protocol

Support

If you encounter any issues or have questions:

Open an issue on GitHub
Check existing issues for solutions

Made with love for the medical informatics community

Install

Configuration

Environment variables

WHO_CLIENT_ID

WHO ICD-11 API Client ID. Required only for ICD-11 tools (5 tools); the server starts without it and other terminologies (LOINC, RxNorm, MeSH, ATC, CID-10) work unauthenticated. Get credentials at https://icd.who.int/icdapi.

WHO_CLIENT_SECRETsecret

WHO ICD-11 API Client Secret. Required only for ICD-11 tools.

WHO_ICD11_RELEASE_ID

ICD-11 release to query (e.g. 2024-01, 2025-01). Optional; defaults to 2024-01.

ENABLE_SNOMED_TOOLS

Set to 'true' to register the 6 SNOMED-dependent tools (snomed_search, snomed_concept, snomed_hierarchy, snomed_descriptions, snomed_ecl, plus map_snomed_to_icd10). Disabled by default because the historical public IHTSDO Snowstorm endpoint was retired (HTTP 410 Gone). Requires SNOMED_BASE_URL pointing at a working self-hosted Snowstorm.

SNOMED_BASE_URL

Base URL of a self-hosted Snowstorm instance (e.g. https://my-snowstorm.example.com/snowstorm/snomed-ct). Required only when ENABLE_SNOMED_TOOLS is true.

SNOMED_LANGUAGE

Accept-Language tag(s) for SNOMED responses (e.g. pt, pt-BR, es). Optional; defaults to 'en'. Composite values with q-weights depend on the upstream Snowstorm instance.

LOG_LEVEL

pino log level (debug, info, warn, error, fatal). Optional; defaults to 'info'. Logs go to stderr only — never stdout (which is the MCP stdio transport).

Arguments

--http

--portdefault 3000

--hostdefault 0.0.0.0

claude_desktop_config.json

{
  "mcpServers": {
    "medical-terminologies-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "medical-terminologies-mcp@1.5.7"
      ],
      "env": {
        "WHO_CLIENT_ID": "<YOUR_WHO_CLIENT_ID>",
        "WHO_CLIENT_SECRET": "<YOUR_WHO_CLIENT_SECRET>",
        "WHO_ICD11_RELEASE_ID": "<YOUR_WHO_ICD11_RELEASE_ID>",
        "ENABLE_SNOMED_TOOLS": "<YOUR_ENABLE_SNOMED_TOOLS>",
        "SNOMED_BASE_URL": "<YOUR_SNOMED_BASE_URL>",
        "SNOMED_LANGUAGE": "<YOUR_SNOMED_LANGUAGE>",
        "LOG_LEVEL": "<YOUR_LOG_LEVEL>"
      }
    }
  }
}

icd11_search

icd11_lookup

icd11_hierarchy

icd11_chapters

icd11_postcoordination

loinc_search

loinc_details

loinc_answers

loinc_panels

rxnorm_search

rxnorm_concept

rxnorm_ingredients

rxnorm_classes

rxnorm_ndc

mesh_search

mesh_descriptor

mesh_tree

mesh_qualifiers

map_icd10_to_icd11

map_loinc_to_snomed

validate_codes

find_equivalent

atc_classify

atc_lookup

atc_members

cid10_search

cid10_lookup

cid10_chapters

cid10_chapter

terminology_versions

terminology_diff

Medical Terminologies MCP Server

See it in action

Features

Who is this for?

Try the hosted instance (no install)

Installation

Global Installation (Recommended)

Local Installation

Configuration

Claude Desktop

Environment Variables

HTTP transport (hosted / shared deployments)

Hosted on Cloudflare Workers (primary)

Listing on Smithery

Self-hosted Docker (alternative)

Available Tools (31 by default, 37 with SNOMED enabled)

ICD-11 Tools (5)

LOINC Tools (4)

RxNorm Tools (5)

MeSH Tools (4)

SNOMED CT Tools (5, disabled by default)

Crosswalk Tools (5 — map_snomed_to_icd10 requires SNOMED)

ATC Tools (3)

CID-10 Tools (4)

Versioning Tools (2)

Example Outputs

loinc_search — query: "glucose", max_results: 3

rxnorm_ingredients — rxcui: "6809" (metformin)

mesh_descriptor — mesh_id: "D006973" (Hypertension)

Common Workflows

SNOMED CT setup (advanced)

Terminology Licenses

ICD-11 (WHO)

SNOMED CT

LOINC

RxNorm

MeSH

API Rate Limits

Development

Building from source

Running locally

Testing with MCP Inspector

Contributing

Author

License

Acknowledgments

Support

Install

Configuration

Crosswalk Tools (5 — `map_snomed_to_icd10` requires SNOMED)

`loinc_search` — query: "glucose", max_results: 3

`rxnorm_ingredients` — rxcui: "6809" (metformin)

`mesh_descriptor` — mesh_id: "D006973" (Hypertension)