# Linking Umls Concepts

Links entities extracted by OpenMed to UMLS Metathesaurus CUIs using the USER'S OWN UTS...

- Repository: https://github.com/maziyarpanahi/openmed (5755 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add maziyarpanahi/openmed --skill linking-umls-concepts -g -a claude-code -y`
Codex: `npx skills add maziyarpanahi/openmed --skill linking-umls-concepts -g -a codex -y`
Cursor: `npx skills add maziyarpanahi/openmed --skill linking-umls-concepts -g -a cursor -y`
Gemini CLI: `npx skills add maziyarpanahi/openmed --skill linking-umls-concepts -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add maziyarpanahi/openmed`

## Description

Links entities extracted by OpenMed to UMLS Metathesaurus CUIs using the USER'S OWN UTS API key, with nothing from the Metathesaurus bundled or cached. Use when the user wants to normalize concepts across vocabularies to a single CUI, resolve synonyms via the UMLS, filter by semantic type, or cross-walk between SNOMED CT, ICD-10, RxNorm and MeSH through their shared CUI. Trigger keywords: UMLS, CUI, Metathesaurus, UTS API key, semantic type, TUI, MetaMap, QuickUMLS, concept normalization, cross-vocabulary. Pairs after OpenMed NER: consume Disease/Pharmaceutical/Chemical/Anatomy entities from openmed.analyze_text and resolve each span to a CUI out-of-process. UMLS is license-restricted, the Metathesaurus is NEVER bundled; every call uses the user's UTS account.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Linking OpenMed entities to UMLS CUIs

Resolve concept spans that OpenMed extracts to **UMLS Metathesaurus** concepts.
The atom is the **CUI** (Concept Unique Identifier, e.g. `C0011860`): one CUI
unifies synonyms from many source vocabularies (SNOMED CT, ICD-10-CM, RxNorm,
MeSH, LOINC), making the CUI the natural hub for cross-vocabulary normalization.
Every concept also carries one or more **semantic types** (TUIs, e.g. *Disease or
Syndrome* `T047`) for type-based filtering.

> **Hard licensing boundary, read first.** The UMLS Metathesaurus is
> **license-restricted**. OpenMed and this skill **never bundle, ship, or cache**
> Metathesaurus content. Concept linking runs **out-of-process against the NLM
> UTS (UMLS Terminology Services) REST API using the user's own UTS API key**.
> A free UTS account + API key is required (request at uts.nlm.nih.gov and accept
> the UMLS license). The Metathesaurus stays user-supplied: your code holds only
> the key (from the environment) and stores only returned CUIs/strings.

## When to use

- You need **one canonical id across vocabularies**, e.g. to unify a SNOMED CT
  disorder, an ICD-10 code, and a free-text mention onto a single CUI.
- You want **synonym normalization** ("MI", "myocardial infarction", "heart
  attack" → `C0027051`).
- You need **semantic-type filtering** to keep only, say, *Pharmacologic
  Substance* or *Disease or Syndrome* entities.
- You are cross-walking codes and need the CUI as the join key before pivoting to
  RxNorm (`normalizing-rxnorm`) or SNOMED (`mapping-to-snomed`).

## Quick start (user-supplied UTS API key)

The UTS REST API base is `https://uts-ws.nlm.nih.gov/rest`. Authentication uses
your API key as the `apiKey` query parameter (the modern, simplest method).

```python
import os, requests

UTS = "https://uts-ws.nlm.nih.gov/rest"
API_KEY = os.environ["UTS_API_KEY"]          # USER's own key, never hardcoded
VERSION = "current"                           # or a fixed release like 2024AB

The rest: https://github.com/maziyarpanahi/openmed/blob/HEAD/skills/linking-umls-concepts/SKILL.md