# 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](https://github.com/IHTSDO/snowstorm), [Ontoserver](https://ontoserver.csiro.au), [HAPI FHIR](https://hapifhir.io), and other FHIR-compliant terminology servers.

> [!CAUTION]
> **Accuracy disclaimer** — The SNOMED CT data returned by this server is sourced directly from
> authoritative FHIR terminology servers and is accurate at the point of retrieval. However,
> an LLM processes and presents these results to you, and in doing so may introduce
> inaccuracies — rephrasing terms, inferring relationships, or adding context that is not
> present in the original data. Always verify critical clinical information against the
> raw SNOMED CT codes and preferred terms provided in the tool output.

## 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:

| Backend | `SNOMED_BACKEND` | URL variable | Default |
|---------|-----------------|--------------|---------|
| Remote FHIR server | `remote` (default) | `FHIR_REMOTE_URL` | `https://r4.ontoserver.csiro.au/fhir` |
| Local Snowstorm | `local` | `SNOWSTORM_LOCAL_URL` | `http://localhost:8080/fhir` |

Copy `.env.example` and configure:

```bash
cp .env.example .env
```

**Local Snowstorm** (e.g. running on localhost:8080):
```env
SNOMED_BACKEND=local
# SNOWSTORM_LOCAL_URL=http://localhost:8080/fhir  # override if non-default port
```

**Remote server** (default):
```env
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:

```env
# 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

```bash
pip install mcp httpx pydantic
```

### Claude Desktop config (`claude_desktop_config.json`)

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

Using a remote server:
```json
{
  "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

```bash
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:

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

## Requirements

- Python 3.10+
- One of:
  - A local [Snowstorm](https://github.com/IHTSDO/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](https://github.com/IHTSDO/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](https://github.com/IHTSDO/snowstorm?tab=readme-ov-file#option-2---use-docker-recommended) for full details.

```bash
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](https://mlds.ihtsdotools.org/) (Member Licensing & Distribution Service) — a SNOMED International account is required.

After import, verify the FHIR endpoint is available:

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

Then configure this MCP server to use it:

```env
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")
```