Skip to main content
Glama
DICOMweb MCP Server

DICOMweb MCP Server

NPM version NPM downloads build MIT License dicomweb-mcp-server MCP server dicomweb-mcp-server on MCP ServerList

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:

Endpoint

Service

Used by

GET /studies

QIDO-RS

Search studies

GET /studies/{study}/series

QIDO-RS

Search series

GET /studies/{study}/series/{series}/instances

QIDO-RS

Search instances, search structured reports, search encapsulated PDF reports

GET /studies/{study}/series/{series}/instances/{instance}/metadata

WADO-RS

Get instance metadata, get structured report text, get encapsulated PDF report text

GET /studies/{study}/series/{series}/instances/{instance}/frames/{frame}/rendered

WADO-RS

Render instance frame

Related MCP server: DICOM MCP Server

Installation

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

Variable

Required

Description

DICOMWEB_HOST

Yes

Base URL of the DICOMweb server (used for both QIDO-RS and WADO-RS requests)

DICOMWEB_AUTH

No

Authentication type: basic or bearer

DICOMWEB_USER

Conditional

Username — required when DICOMWEB_AUTH=basic

DICOMWEB_PASS

Conditional

Password — required when DICOMWEB_AUTH=basic

DICOMWEB_TOKEN

Conditional

Bearer token — required when DICOMWEB_AUTH=bearer

DICOMWEB_TIMEOUT

No

Fetch timeout in milliseconds. Omit to disable.

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.

Parameter

Type

Description

query

string

Space-separated key=value filter string (see Query Syntax). Pass "" to return all studies.

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.

Parameter

Type

Description

studyInstanceUid

string

Study Instance UID — obtain from find-studies

query

string

Space-separated key=value filter string. Pass "" to return all series.


find-instances

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

Parameter

Type

Description

studyInstanceUid

string

Study Instance UID — obtain from find-studies

seriesInstanceUid

string

Series Instance UID — obtain from find-series

query

string

Space-separated key=value filter string. Pass "" to return all instances.


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).

Parameter

Type

Description

studyInstanceUid

string

Study Instance UID — obtain from find-studies

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.

Parameter

Type

Description

studyInstanceUid

string

Study Instance UID

seriesInstanceUid

string

Series Instance UID

sopInstanceUid

string

SOP Instance UID — obtain from find-encapsulated-pdf-reports

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.

Parameter

Type

Description

studyInstanceUid

string

Study Instance UID — obtain from find-studies


get-structured-report-text

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

Parameter

Type

Description

studyInstanceUid

string

Study Instance UID

seriesInstanceUid

string

Series Instance UID

sopInstanceUid

string

SOP Instance UID — obtain from find-structured-reports


get-instance-metadata

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

Parameter

Type

Description

studyInstanceUid

string

Study Instance UID

seriesInstanceUid

string

Series Instance UID

sopInstanceUid

string

SOP Instance UID — obtain from find-instances


render-instance-frame

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

Parameter

Type

Description

studyInstanceUid

string

Study Instance UID

seriesInstanceUid

string

Series Instance UID

sopInstanceUid

string

SOP Instance UID — obtain from find-instances

frame

integer

1-based frame index (use 1 for single-frame instances)

outputFormat

enum

image/jpeg or image/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

Format

Example

DICOM keyword name

PatientName=DOE*

8-digit hex tag

00100020=12345

Special keys

Key

Description

limit=N

Maximum number of results to return

offset=N

Skip the first N results (for pagination)

fuzzymatching=true

Enable fuzzy (phonetic) name matching

includefield=all

Request all available DICOM attributes

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.

dicomweb-mcp-server MCP server

Available Tools

9 tools
find-encapsulated-pdf-reportsA

Finds all Encapsulated PDF DICOM instances in a study by searching for DOC-modality series and filtering by EP SOP Class UIDs. Requires a Study Instance UID from find-studies.

Inputs: studyInstanceUid (required).

find-instancesA

Searches DICOM instances within a single series, sorted by Instance Number ascending. Requires Study and Series Instance UIDs from find-studies and find-series.

Inputs: query (required), studyInstanceUid (required), seriesInstanceUid (required).

find-seriesA

Searches DICOM series within a single study. Returns series sorted by series date, newest first. Does not retrieve instances or image data. Requires a Study Instance UID from find-studies.

Inputs: query (required), studyInstanceUid (required).

find-structured-reportsA

Finds all Structured Report (SR) DICOM instances in a study by searching for SR-modality series and filtering by SR SOP Class UIDs. Requires a Study Instance UID from find-studies.

Inputs: studyInstanceUid (required).

find-studiesA

Searches DICOM studies on the configured DICOMweb server. Returns studies sorted by study date, newest first. Does not retrieve series, instances, or image data.

Inputs: query (required).

get-encapsulated-pdf-report-textA

Retrieves and converts an Encapsulated PDF instance to human-readable text. Requires Study, Series, and SOP Instance UIDs from find-encapsulated-pdf-reports. Does not retrieve image data.

Inputs: sopInstanceUid (required), studyInstanceUid (required), seriesInstanceUid (required).

get-instance-metadataA

Retrieves and converts a DICOM instance to human-readable text. Requires Study, Series, and SOP Instance UIDs from find-instances. Does not retrieve image data.

Inputs: sopInstanceUid (required), studyInstanceUid (required), seriesInstanceUid (required).

get-structured-report-textA

Retrieves and converts a Structured Report (SR) instance to human-readable text. Requires Study, Series, and SOP Instance UIDs from find-structured-reports. Does not retrieve image data.

Inputs: sopInstanceUid (required), studyInstanceUid (required), seriesInstanceUid (required).

render-instance-frameA

Renders a specific frame from a DICOM instance to an image format. Requires Study, Series, and SOP Instance UIDs from find-instances, and a frame number. Returns the rendered image as a base64-encoded string.

Inputs: sopInstanceUid (required), studyInstanceUid (required), seriesInstanceUid (required), frame, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a specific resource or action: studies, series, instances, encapsulated PDF reports, structured reports, and metadata/rendering. There is clear separation between find and get operations, and between different document types, preventing confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb-noun pattern with lowercase and hyphens (e.g., find-studies, get-instance-metadata, render-instance-frame). No mixing of conventions.

    Tool Count5/5

    With 9 tools, the set is well-scoped for a DICOMweb server focused on querying and retrieving data. Each tool has a clear role, and the number aligns with typical best practices.

    Completeness4/5

    The server covers core query and retrieval operations for studies, series, instances, and special document types. Missing write operations (store, delete) and bulk retrieval, but for a read-oriented viewer, the surface is reasonably complete.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to query and analyze medical imaging metadata from DICOM servers, including patient information, studies, series, and instances, as well as extract text from encapsulated PDF documents.
      108
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to query, read, download, and move medical imaging data on DICOM servers (PACS, VNA) including patient searches, study retrieval, PDF report extraction, and image transfer to AI endpoints for analysis.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for reading C2PA content provenance manifests from media files, enabling natural language queries about AI-generated content, signatures, and provenance.
      3
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that lets AI assistants read and visually analyze local documents — PDFs, Excel spreadsheets, CSV files, Word documents, PowerPoint presentations, and images.
      4
      49 npm
      100 PyPI
      MIT