SNOMED CT MCP Server

An MCP server that provides SNOMED CT clinical terminology lookup via any FHIR R4 terminology server that supports SNOMED CT and ECL (Expression Constraint Language).

Compatible servers include Snowstorm, Ontoserver, HAPI FHIR, and other FHIR-compliant terminology servers.

Tools

snomed_lookup

Search for SNOMED CT concepts by clinical term.

Parameters:

• term (string, required) — Clinical term to search, e.g. "exercise therapy", "diabetes", "appendectomy"

• domain (string, optional, default "all") — Scope the search to a SNOMED CT top-level hierarchy:

  • "clinical_finding" — diseases, signs, symptoms

  • "procedure" — surgeries, therapies, diagnostic tests

  • "observable_entity" — measurements, scores, lab values

  • "body_structure" — anatomical structures, organs, body regions

  • "organism" — bacteria, viruses, organisms

  • "substance" — chemicals, dietary substances, biological substances

  • "pharmaceutical_product" — medications, vaccines, clinical drugs

  • "specimen" — blood samples, tissue specimens

  • "special_concept" — special SNOMED concepts

  • "physical_object" — devices, implants, instruments

  • "physical_force" — radiation, thermal, mechanical forces

  • "event" — accidents, incidents, occurrences

  • "environment" — locations, geographic regions, settings

  • "social_context" — occupations, religions, ethnic groups

  • "situation" — clinical situations with explicit context

  • "staging_and_scales" — tumor staging, assessment scales

  • "qualifier_value" — severity, laterality, other qualifiers

  • "record_artifact" — clinical documents, forms, records

  • "snomed_model_component" — metadata and model components

  • "all" — search across all configured domains

• count (integer, optional, default 10, max 50) — Max results to return

snomed_get_by_code

Fetch full details for a known SNOMED CT concept ID.

Parameters:

• code (string, required) — Numeric SNOMED CT concept ID, e.g. "229070002"

snomed_get_related

Navigate the SNOMED CT hierarchy for a concept. Returns the concept's parents (immediate supertypes), children (immediate subtypes), and siblings (other children of the same parents).

Parameters:

• code (string, required) — Numeric SNOMED CT concept ID, e.g. "229070002"

Prompts

normalize_clinical_term

A structured multi-step prompt that guides the LLM through normalizing free-text or lay language into a verified SNOMED CT concept. The workflow: parse the input, expand abbreviations, generate candidate clinical terms, search each via snomed_lookup, and select the best match with a confidence score.

Parameters:

• raw_input (string, required) — The original user input in any language or format (lay, clinical, abbreviated)

• clinical_context (string, optional) — Clinical domain hint to narrow the search (e.g. "musculoskeletal", "cardiology")

explore_concept

A structured multi-step prompt that guides the LLM through exploring concepts related to a starting concept, driven by the user's semantic intent. Goes beyond hierarchy navigation by combining IS-A traversal with targeted searches across different SNOMED domains — useful for questions like "what quantifiable measures relate to this concept?" or "what procedures are associated with this finding?".

Parameters:

• code (string, required) — SNOMED CT concept ID to explore from, e.g. "282097004"

• intent (string, required) — What the user is looking for, e.g. "quantifiable measures", "related procedures", "assessment scales"

Configuration

The server supports two backends, controlled by the SNOMED_BACKEND environment variable:

Copy .env.example and configure:

cp .env.example .env

Local Snowstorm (e.g. running on localhost:8080):

SNOMED_BACKEND=local
# SNOWSTORM_LOCAL_URL=http://localhost:8080/fhir  # override if non-default port

Remote server (default):

SNOMED_BACKEND=remote
FHIR_REMOTE_URL=https://r4.ontoserver.csiro.au/fhir

Domain filtering

By default all 19 SNOMED CT top-level hierarchies are searchable. Use SNOMED_DOMAINS to restrict which domains are exposed in the tool schema:

# Only expose three domains:
SNOMED_DOMAINS=clinical_finding,procedure,pharmaceutical_product

# Expose all domains (default):
SNOMED_DOMAINS=all

When set, the server dynamically builds the domain enum and descriptions so the LLM only sees the configured domains. See .env.example for the full list.

Installation

pip install mcp httpx pydantic

Claude Desktop config (claude_desktop_config.json)

Using a local Snowstorm instance:

{
  "mcpServers": {
    "snomed-ct": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "SNOMED_BACKEND": "local"
      }
    }
  }
}

Using a remote server:

{
  "mcpServers": {
    "snomed-ct": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "SNOMED_BACKEND": "remote",
        "FHIR_REMOTE_URL": "https://r4.ontoserver.csiro.au/fhir"
      }
    }
  }
}

Claude Code

claude mcp add snomed-ct python /absolute/path/to/server.py

The server reads its configuration from the .env file. You can also pass env vars inline:

SNOMED_BACKEND=local claude mcp add snomed-ct python /absolute/path/to/server.py

Requirements

• Python 3.10+

• One of:

  • A local Snowstorm instance with SNOMED CT loaded

  • A remote FHIR R4 terminology server with SNOMED CT and ECL support

Running a local terminology server with Snowstorm

Snowstorm is SNOMED International's open-source terminology server. It provides a FHIR R4 endpoint and full ECL support, making it the recommended local backend for this MCP server.

Quick start with Docker

The fastest way to get Snowstorm running locally is with Docker Compose. See the Snowstorm documentation for full details.

git clone https://github.com/IHTSDO/snowstorm.git
cd snowstorm
docker-compose up -d

Once Snowstorm is running, you need to import a SNOMED CT release package. You can obtain RF2 release files from MLDS (Member Licensing & Distribution Service) — a SNOMED International account is required.

After import, verify the FHIR endpoint is available:

curl http://localhost:8080/fhir/metadata

Then configure this MCP server to use it:

SNOMED_BACKEND=local
SNOWSTORM_LOCAL_URL=http://localhost:8080/fhir

Example usage

Look up the SNOMED CT code for "exercise therapy"
→ snomed_lookup(term="exercise therapy", domain="procedure")

Get all synonyms for concept 229070002
→ snomed_get_by_code(code="229070002")

Find SNOMED codes for "chest pain"
→ snomed_lookup(term="chest pain", domain="clinical_finding")

Navigate the hierarchy for "Walking distance"
→ snomed_get_related(code="165263003")