dicomweb-mcp-server is a Model Context Protocol (MCP) server used to expose DICOM archives that conform to the DICOMweb standard to AI assistants. Any MCP-capable client can use natural language to search studies, series, and instances, inspect metadata, read Structured Reports and Encapsulated PDF Reports, and render image frames.
Prerequisites:
- Node.js 20 or later.
- A running DICOMweb server that supports QIDO-RS and WADO-RS (for example, orthanc).
- The DICOMweb server must support the relevant endpoints listed in the documentation.
Installation and running: The recommended approach is to use npx, with no local installation required. The server reads configuration from a .env file in the directory where the script is located. You need to create a .env file and fill in the connection information for the DICOMweb server to connect to, placing the file next to the server execution location or in the working directory configured in the MCP client.
MCP client configuration: The server can be added to claude_desktop_config.json, or all environment variables can be provided directly in the env block instead of using a .env file. VS Code (GitHub Copilot Agent Mode) can be added to VS Code's settings.json or the workspace .vscode/mcp.json. Cursor can be added to the project root's .cursor/mcp.json, or the global ~/.cursor/mcp.json.
Available tools:
- Search DICOM studies: Search 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".
- Search DICOM series: Search series within a single study; results are sorted by series date, newest first.
- Search DICOM instances: Search instances within a single series; results are sorted by Instance Number in ascending order.
- find-encapsulated-pdf-reports: Find all encapsulated PDF instances in a study by locating 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: Retrieve the DICOM instance of an encapsulated PDF and extract its text content. Note: text extraction only works for searchable (text-based) PDFs; PDFs composed entirely of scanned page images with no embedded text layer will yield little or no text, and in such cases OCR will not be 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: Find all Structured Report (SR) instances in a study by locating SR modality series and filtering by known SR SOP Class UIDs.
- get-structured-report-text: Retrieve a Structured Report instance and convert it into human-readable text.
- get-instance-metadata: Retrieve and format all DICOM attributes of a single instance as human-readable text, without retrieving pixel data.
- render-instance-frame: Render a specified frame from a DICOM instance and return 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 parameter description: The query parameter accepted by the search tools is a space-separated key=value list. Wildcards * are supported in string values when the DICOMweb server allows it.
Typical workflow: A natural conversation sequence with the MCP server usually proceeds as follows:
- Search for studies—use find-studies with a patient name or date range.
- Browse series—call find-series using the Study Instance UID returned in step 1.
- List instances—call find-instances using the Study and Series UIDs from steps 1–2.
- Inspect or render—use get-instance-metadata to view DICOM attributes, or render-instance-frame to view pixel data.
- Read SR reports—first find-structured-reports, then get-structured-report-text to retrieve the SR document.
- Read PDF reports—first find-encapsulated-pdf-reports, then get-encapsulated-pdf-report-text to retrieve the encapsulated PDF document.
License: dicomweb-mcp-server is released under the MIT License.
