dicomweb-mcp-server

A Model Context Protocol (MCP) server that exposes a DICOMweb-compliant DICOM archive to AI assistants. It lets any MCP-capable client search studies, series and instances, inspect metadata, read Structured and Encapsulated PDF Reports, and render image frames — all through natural language.

Requirements

• Node.js 20 or later
• A running DICOMweb server supporting QIDO-RS and WADO-RS (e.g. orthanc)

The following endpoints must be supported by the DICOMweb server:

Installation

Using npx (recommended — no local install needed)

npx dicomweb-mcp-server

The server reads its configuration from a .env file located in the same directory as the script (see Configuration below).

Global install

npm install -g dicomweb-mcp-server
dicomweb-mcp-server

Configuration

Create a .env file with the connection details for your DICOMweb server. Place the file next to wherever the server is executed from (or in the working directory you configure in your MCP client).

# Required
DICOMWEB_HOST=https://your-dicomweb-server/dicomweb

# Optional — authentication
DICOMWEB_AUTH=basic        # basic | bearer
DICOMWEB_USER=username     # required when DICOMWEB_AUTH=basic
DICOMWEB_PASS=password     # required when DICOMWEB_AUTH=basic
DICOMWEB_TOKEN=your-token  # required when DICOMWEB_AUTH=bearer

# Optional — request timeout (milliseconds)
DICOMWEB_TIMEOUT=30000

MCP Client Setup

Claude Desktop

Add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "dicomweb": {
      "command": "npx",
      "args": ["-y", "dicomweb-mcp-server"],
      "env": {
        "DICOMWEB_HOST": "https://your-dicomweb-server/dicomweb"
      }
    }
  }
}

You can supply all environment variables directly in the env block instead of using a .env file.

VS Code (GitHub Copilot Agent Mode)

Add to your VS Code settings.json or workspace .vscode/mcp.json:

{
  "servers": {
    "dicomweb": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "dicomweb-mcp-server"],
      "env": {
        "DICOMWEB_HOST": "https://your-dicomweb-server/dicomweb"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root, or to the global ~/.cursor/mcp.json:

{
  "mcpServers": {
    "dicomweb": {
      "command": "npx",
      "args": ["-y", "dicomweb-mcp-server"],
      "env": {
        "DICOMWEB_HOST": "https://your-dicomweb-server/dicomweb"
      }
    }
  }
}

Available Tools

find-studies

Searches DICOM studies on the configured DICOMweb server. Results are sorted by study date, newest first.

Example prompts

• "Find all CT studies for patient John Doe"
• "Search for studies from January 2024"

find-series

Searches DICOM series within a single study. Results are sorted by series date, newest first.

find-instances

Searches DICOM instances within a single series. Results are sorted by Instance Number ascending.

find-encapsulated-pdf-reports

Finds all Encapsulated PDF instances in a study by looking for DOC-modality series and filtering by the Encapsulated PDF SOP Class UID (1.2.840.10008.5.1.4.1.1.104.1).

Example prompts

• "Find all PDF reports in study 1.2.3.4"
• "Are there any encapsulated PDF documents in this study?"

get-encapsulated-pdf-report-text

Retrieves an Encapsulated PDF DICOM instance and extracts its text content.

Note: Text extraction only works for searchable (text-based) PDFs. PDFs that consist entirely of scanned page images without an embedded text layer will yield little or no text. In those cases, no OCR is performed.

Example prompts

• "Read the PDF report for SOP instance 1.2.3.4.5"
• "What does the encapsulated PDF document say?"

find-structured-reports

Finds all Structured Report (SR) instances in a study by looking for SR-modality series and filtering by known SR SOP Class UIDs.

get-structured-report-text

Retrieves a Structured Report instance and converts it to human-readable text.

get-instance-metadata

Retrieves and formats all DICOM attributes of a single instance as human-readable text. Does not retrieve pixel data.

render-instance-frame

Renders a specific frame from a DICOM instance and returns it as an inline image (JPEG or PNG).

Example prompt

• "Show me the first frame of SOP instance 1.2.3.4.5 as a JPEG"

Query Syntax

The query parameter accepted by the search tools is a space-separated list of key=value pairs.

Key formats

Special keys

Examples

PatientName=DOE*
StudyDate=20240101-20241231 ModalitiesInStudy=CT
00100020=ABC123 limit=10
fuzzymatching=true PatientName=Smith

Wildcard * is supported in string values where the DICOMweb server allows it.

Typical Workflow

A natural conversational sequence with the MCP server looks like this:

1. Search studies — find-studies with a patient name or date range.
2. Browse series — find-series with the Study Instance UID returned in step 1.
3. List instances — find-instances with Study and Series UIDs from steps 1–2.
4. Inspect or render — get-instance-metadata for DICOM attributes, or render-instance-frame to view pixel data.
5. Read SR reports — find-structured-reports then get-structured-report-text for SR documents.
6. Read PDF reports — find-encapsulated-pdf-reports then get-encapsulated-pdf-report-text for Encapsulated PDF documents.

License

dicomweb-mcp-server is released under the MIT License.