Skip to content

feordin/nih-umls-mcp

BranchesTags

Repository files navigation

NIH UMLS MCP Server

An MCP (Model Context Protocol) server that provides access to the NIH UMLS (Unified Medical Language System) API and the NIH VSAC (Value Set Authority Center) FHIR API. This server enables AI models to search medical terminology, look up concept definitions, explore relationships between medical concepts, map codes between different medical coding systems, and work with curated clinical value sets.

Overview

The Unified Medical Language System (UMLS) integrates biomedical terminology from many sources and provides a mapping structure among these vocabularies. It includes over 200 source vocabularies and classification systems, containing millions of names for medical concepts.

The Value Set Authority Center (VSAC) is an NLM repository of curated value sets — collections of medical codes from standard code systems (SNOMED CT, ICD-10, LOINC, CPT, RxNorm, etc.) that define clinical concepts for electronic Clinical Quality Measures (eCQMs), C-CDA documents, and health IT standards.

This MCP server exposes both APIs through standardized MCP tools, making it easy for AI assistants to:

  • Search for medical concepts and terminology
  • Get detailed concept information and definitions
  • Explore relationships between concepts (parent/child hierarchies)
  • Map codes between different medical coding systems (e.g., ICD-10 ↔ SNOMED CT)
  • Look up specific codes from vocabularies like ICD-10, SNOMED, RxNorm, LOINC, etc.
  • Search and retrieve curated clinical value sets
  • Expand value sets to get all member codes
  • Validate whether a code belongs to a value set
  • Test hierarchical subsumption relationships between codes

Prerequisites

  1. UMLS API Key: You need a UMLS API key to use this server (the same key works for both UMLS and VSAC). To obtain one:

Installation

Option 1: Install from PyPI

pip install nih-umls-mcp

Option 2: Install from source

# Clone the repository
git clone https://github.com/feordin/nih-umls-mcp.git
cd nih-umls-mcp

# Install the package
pip install -e .

Option 3: Install with uv (recommended for MCP usage)

# Using uvx (no installation needed)
uvx nih-umls-mcp

Upgrading

# If installed with pip
pip install --upgrade nih-umls-mcp

# If installed with uv
uv tool upgrade nih-umls-mcp

Configuration

The server requires your UMLS API key to be set as an environment variable:

export UMLS_API_KEY="your-api-key-here"

Configuring with Claude Desktop

To use this server with Claude Desktop, add the following to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "nih-umls": {
      "command": "python",
      "args": ["-m", "nih_umls_mcp.server"],
      "env": {
        "UMLS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Or if using uvx:

{
  "mcpServers": {
    "nih-umls": {
      "command": "uvx",
      "args": ["nih-umls-mcp"],
      "env": {
        "UMLS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

UMLS Tools

1. search_umls

Search for medical concepts, terms, or codes in the UMLS.

Parameters:

  • query (string, required): Search term, medical concept, or code
  • search_type (string, optional): Type of search - "exact", "words" (default), "leftTruncation", "rightTruncation", "normalizedString", "approximate"
  • page_size (integer, optional): Number of results (1-25, default: 10)

Example:

Search for "diabetes mellitus" to find relevant concepts

2. get_concept

Get detailed information about a specific UMLS concept using its CUI (Concept Unique Identifier).

Parameters:

  • cui (string, required): Concept Unique Identifier (e.g., "C0009044")

Example:

Get details for concept C0009044 (Closed Fracture)

3. get_definitions

Get all definitions for a concept from various medical vocabularies.

Parameters:

  • cui (string, required): Concept Unique Identifier

Example:

Get definitions for diabetes mellitus concept

4. get_concept_relations

Get relationships between concepts (parent concepts, child concepts, related terms).

Parameters:

  • cui (string, required): Concept Unique Identifier
  • page_size (integer, optional): Number of results (1-25, default: 10)

Example:

Get parent and child concepts for diabetes mellitus

5. crosswalk_codes

Map a medical code from one coding system to equivalent codes in other systems.

Parameters:

  • source (string, required): Source vocabulary (e.g., "ICD10CM", "SNOMEDCT_US", "RXNORM", "LOINC")
  • code (string, required): The code to map
  • target_source (string, optional): Specific target vocabulary to filter results
  • page_size (integer, optional): Number of results (1-25, default: 10)

Common vocabulary abbreviations:

  • ICD10CM - ICD-10 Clinical Modification
  • ICD9CM - ICD-9 Clinical Modification
  • SNOMEDCT_US - SNOMED CT US Edition
  • RXNORM - RxNorm (medications)
  • LOINC - Logical Observation Identifiers Names and Codes
  • CPT - Current Procedural Terminology
  • HCPCS - Healthcare Common Procedure Coding System
  • ICD10PCS - ICD-10 Procedure Coding System
  • NDC - National Drug Code

Example:

Map ICD-10 code E11.9 (Type 2 diabetes without complications) to SNOMED CT

6. get_source_concept

Get information about a specific code from a particular medical vocabulary.

Parameters:

  • source (string, required): Source vocabulary abbreviation
  • code (string, required): The code in that vocabulary

Example:

Get information about ICD-10 code E11.9

VSAC Tools

7. search_value_sets

Search the VSAC for curated value sets by title, keyword, publisher, or contained code.

Parameters:

  • title (string, optional): Search by title (e.g., "Diabetes", "Hypertension")
  • keyword (string, optional): Search by keyword/tag
  • publisher (string, optional): Filter by publishing organization (e.g., "Mathematica", "NCQA")
  • code (string, optional): Find value sets containing a specific code
  • count (integer, optional): Number of results (default: 10)

Example:

Search for value sets related to "Diabetes" to find eCQM-relevant code groupings

8. get_value_set

Get a value set definition by its OID (Object Identifier).

Parameters:

  • oid (string, required): The value set OID (e.g., "2.16.840.1.113883.3.464.1003.103.12.1001")

Example:

Get the definition of the Diabetes value set used in CMS quality measures

9. expand_value_set

Expand a value set to get all its member codes. Returns every code with its code system, value, and display name.

Parameters:

  • oid (string, required): The value set OID
  • filter (string, optional): Text to filter codes within the expansion
  • count (integer, optional): Number of codes to return (default: 100)
  • offset (integer, optional): Starting offset for pagination (default: 0)

Example:

Expand the Diabetes value set to get all ICD-10 and SNOMED codes it contains

10. validate_code_in_value_set

Check if a specific code is a member of a value set.

Parameters:

  • oid (string, required): The value set OID to check against
  • code (string, required): The code to validate
  • system (string, optional): Code system URI (required if the value set spans multiple code systems)

Common code system URIs:

  • http://snomed.info/sct - SNOMED CT
  • http://hl7.org/fhir/sid/icd-10-cm - ICD-10-CM
  • http://loinc.org - LOINC
  • http://www.nlm.nih.gov/research/umls/rxnorm - RxNorm
  • http://www.ama-assn.org/go/cpt - CPT

Example:

Check if ICD-10 code E11.9 is in the Diabetes value set for eCQM reporting

11. lookup_code

Look up details about a specific code in a code system via VSAC.

Parameters:

  • system (string, required): Code system URI (see common URIs above)
  • code (string, required): The code to look up
  • version (string, optional): Code system version

Example:

Look up SNOMED CT code 44054006 to get its display name and properties

12. check_code_subsumption

Test whether one code subsumes (is an ancestor of) another in a hierarchical code system.

Parameters:

  • system (string, required): Code system URI (e.g., "http://snomed.info/sct")
  • code_a (string, required): The potential ancestor/broader code
  • code_b (string, required): The potential descendant/narrower code

Returns: "subsumes", "subsumed-by", "equivalent", or "not-subsumed"

Example:

Check if SNOMED "Diabetes mellitus" subsumes "Type 2 diabetes mellitus"

Usage Examples

Example 1: Finding a Medical Concept

User: "What is the UMLS concept for Type 2 Diabetes?"

AI uses search_umls:
- query: "Type 2 Diabetes Mellitus"
- search_type: "words"

Returns CUI C0011860 with name "Diabetes Mellitus, Non-Insulin-Dependent"

Example 2: Code Mapping

User: "What is the SNOMED code for ICD-10 code E11.9?"

AI uses crosswalk_codes:
- source: "ICD10CM"
- code: "E11.9"
- target_source: "SNOMEDCT_US"

Returns SNOMED code 44054006 and other equivalent codes

Example 3: Understanding Relationships

User: "What are the subtypes of diabetes?"

AI first uses search_umls to find diabetes CUI, then uses get_concept_relations
to explore child concepts and related terms.

Example 4: Finding Value Set Codes for Quality Measures

User: "What codes count as Diabetes for eCQM reporting?"

AI uses search_value_sets with title "Diabetes" to find relevant value sets,
then uses expand_value_set to get all member codes (ICD-10, SNOMED CT, etc.)
from the appropriate value set.

Example 5: Validating a Code Against a Value Set

User: "Does ICD-10 code E11.9 qualify for the Diabetes quality measure?"

AI uses validate_code_in_value_set:
- oid: "2.16.840.1.113883.3.464.1003.103.12.1001"
- code: "E11.9"
- system: "http://hl7.org/fhir/sid/icd-10-cm"

Returns true/false indicating membership.

Example 6: Checking Code Hierarchy

User: "Is Type 2 diabetes a subtype of diabetes mellitus in SNOMED?"

AI uses check_code_subsumption:
- system: "http://snomed.info/sct"
- code_a: "73211009" (Diabetes mellitus)
- code_b: "44054006" (Type 2 diabetes)

Returns "subsumes" confirming the hierarchical relationship.

Development

Running Tests

pip install -e ".[dev]"
pytest

Project Structure

nih-umls-mcp/
├── src/
│   └── nih_umls_mcp/
│       ├── __init__.py
│       ├── server.py          # MCP server implementation
│       ├── umls_client.py     # UMLS REST API client
│       └── vsac_client.py     # VSAC FHIR API client
├── examples/
│   ├── test_server.py         # Tool registration verification
│   └── client_example.py      # Live API usage example
├── pyproject.toml
└── README.md

API Rate Limits

Both the UMLS and VSAC APIs share the same rate limit:

  • Maximum 20 requests per second per IP address
  • The server doesn't currently implement client-side rate limiting, so be mindful of usage patterns

Troubleshooting

"UMLS_API_KEY environment variable is required"

HTTP 401 Unauthorized

  • Your API key may be invalid or expired
  • Regenerate your API key from your UTS profile

HTTP 404 Not Found

  • The CUI, code, or value set OID you're looking up doesn't exist
  • Check the spelling and format of identifiers

Resources

Disclaimer

This is an independent, community-built project and is not an official product of the National Institutes of Health (NIH) or the National Library of Medicine (NLM). It simply provides a convenient interface to their publicly available APIs.

License

MIT License - see LICENSE file for details.

Contributing

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

About

An MCP server that serves as a wrapper for the NIH UMLS Api

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 4

v0.3.1 Latest
Mar 17, 2026
+ 3 releases

Packages

 
 
 

Contributors

Languages