PantelisGeorgiadis/dicomweb-mcp-server

dicomweb-mcp-server
A [Model Context Protocol (MCP)][mcp-url] 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][orthanc-url])
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 |
Installation
Using npx (recommended — no local install needed)
The server reads its configuration from a .env file located in the **same directory as the script** (see Configuration below).
Global install
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).
| 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:
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:
Cursor
Add to .cursor/mcp.json in your project root, or to the global ~/.cursor/mcp.json:
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).