Dicom Mcp

DICOM MCP Server - Medical Imaging AI Integration 🏥

[](https://opensource.org/licenses/MIT) [](https://github.com/modelcontextprotocol/python-sdk) [](https://github.com/jlowin/fastmcp) [](https://www.mcpjam.com)

This version uses MCP Jam exclusively for development, testing, and LLM integration. Note that if you are using the Cursor IDE, or others, you can configure the IDE to also access the server in some cases, in ~/.cursor/mcp.json, etc. See for details.

Enables AI assistants to query, read, and move data on PACS using the standard Model Context Protocol (MCP), with Orthanc as the reference implementation. You can use your own APIKEY (e.g. for ChatGPT) and run it locally for development using ChatGPT as the LLM. Also integrated with FHIR and a mini-RIS DB.

✨ Core Capabilities

dicom-mcp provides tools to:

• 🔍 Query DICOM: Search for patients, studies, series, and instances using various criteria
• 📄 Read DICOM Reports (PDF): Retrieve DICOM instances containing encapsulated PDFs (e.g., clinical reports) and extract the text content
• 📄 Create Radiology Reports: Generate radiology reports in PDF format and attach to PACS
• ➡️ Send DICOM Images: Send series or studies to other DICOM destinations, e.g. AI endpoints for image segmentation, classification, etc.
• ⚙️ FHIR Integration: Query and manage FHIR resources (Patient, ImagingStudy, ServiceRequest, etc.)
• ⚙️ Mini-RIS: Manage radiology orders, worklists, and reporting workflows
• ⚙️ MWL/MPPS: Modality Worklist and Modality Performed Procedure Step services
• ⚙️ Utilities: Manage connections, switch servers, and understand query options

🚀 Quick Start

📥 Installation

Install using pip by cloning the repository:

# Clone and set up development environment
gh repo clone sscotti/dicom-mcp
cd dicom-mcp

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install with dependencies
pip install -e ".[dev]"

⚙️ Configuration

dicom-mcp requires a YAML configuration file (configuration.yaml or similar) defining DICOM nodes and calling AE titles. Adapt the configuration or keep as is for compatibility with the sample Orthanc server.

# DICOM nodes configuration
nodes:
  main:
    host: "localhost"
    port: 4242
    ae_title: "ORTHANC"
    description: "Local Orthanc DICOM server (Primary)"
  
  secondary:
    host: "localhost"
    port: 4243
    ae_title: "ORTHANC2"
    description: "Local Orthanc DICOM server (Secondary)"

current_node: "main"
calling_aet: "MCPSCU"

# FHIR server configuration (optional)
# You can configure multiple FHIR servers and switch between them
fhir_servers:
  firely:
    base_url: "https://server.fire.ly"
    description: "Firely FHIR Test Server (public, no API key needed)"
  
  siim:
    base_url: "https://hackathon.siim.org/fhir"
    api_key: "${SIIM_API_KEY}"  # Set in .env file
    description: "SIIM Hackathon FHIR server"
  
  # Uncomment to use a local HAPI FHIR server
  hapi_local:
    base_url: "http://localhost:8080/fhir"
    description: "Local HAPI FHIR server"

current_fhir: "hapi_local"  # Active FHIR server: firely, siim, or hapi_local, make sure to start the local hapi fhir server before starting the MCP server

# The server will expose all DICOM tools and FHIR tools via standard MCP protocol

# Mini-RIS MySQL database configuration (optional)
mini_ris:
  host: "localhost"
  port: 3306
  user: "orthanc_ris_app"
  password: "${MINI_RIS_DB_PASSWORD}"
  database: "orthanc_ris"
  pool_size: 5

> [!WARNING] > DICOM-MCP is not meant for clinical use, and should not be connected with live hospital databases or databases with patient-sensitive data. Doing so could lead to both loss of patient data, and leakage of patient data onto the internet. DICOM-MCP can be used with locally hosted open-weight LLMs for complete data privacy. > > [!NOTE] > This project uses MCP Jam for development, testing, and LLM integration needs. The mcp-config.example.json file is provided as a template with relative paths that you can adapt to your setup. That can be imported as JSON into MCPJAM to configure the interface.

Docker Container Setup (Orthancs, FHIR, PostGres and MySQL)

docker-compose up -d
dotenv run -- pytest # uploads dummy pdf data to ORTHANC server

UI at https://localhost:8042 and https://localhost:8043, note that the repo is configured with TLS certs, so https.

HAPI FHIR will be available at http://localhost:8080/fhir

See [FHIR Servers Guide](FHIR_SERVERS.md) for detailed configuration options including Firely test server and SIIM integration.

🔌 Using with MCP Jam (Recommended)

MCP Jam is an alternative tool for testing and exploring your DICOM MCP server. It offers a web interface with Guest Mode for immediate testing without any setup. For a self-contained solution, use the Custom Web UI above!

> Note: MCP Jam Guest Mode may have limitations on certain features like the Resources panel. Resources are still fully accessible via the list_saved_resources and get_saved_resource tools, which work in Guest Mode. For full Resources panel support, you may need to use an account.

Start MCP Jam:

# Navigate to your dicom-mcp directory
cd /path/to/dicom-mcp

# Activate your virtual environment
source venv/bin/activate

# Start MCP Jam (use latest or beta)
npx -y @mcpjam/inspector@latest
# or
npx -y @mcpjam/inspector@beta

Setup Server in MCP Jam:

1. Click "Guest Mode" in the MCP Jam interface (no account required)
2. Add Server Manually with these settings, or import mcp-config.example.json as a template:

• Server Name: DICOM MCP
• Command: {path_to_venv}/bin/python (e.g., venv/bin/python or absolute path)
• Arguments: -m dicom_mcp configuration.yaml --transport stdio
• Environment Variables:
• Name: PYTHONPATH
• Value: src (relative) or absolute path to src directory
• Working Directory: Path to your dicom-mcp project root

Example Configuration (macOS/Linux):

• Command: /absolute/path/to/dicom-mcp/venv/bin/python
• Arguments: -m dicom_mcp configuration.yaml --transport stdio
• Environment Variable: PYTHONPATH = /absolute/path/to/dicom-mcp/src

MCP Jam Interface:

Configure LLM in MCP Jam:

1. Go to the Settings tab
2. Add your API keys for LLM providers:

• OpenAI - For GPT-4, GPT-4o, o1, etc.
• Anthropic - For Claude 3.5 Sonnet, Claude Opus, etc.
• Google Gemini - For Gemini 2.5 Pro, Flash, etc.
• Deepseek - For Deepseek Chat, Reasoner
• Ollama - Auto-detects local models (no API key needed)

1. Go to the Playground tab to start chatting with your DICOM server

Using Your OpenAI API Key in Cursor IDE:

> Note: For MCP server development and testing, MCP Jam is recommended. Cursor is better for general code development with MCP tools available in context.

If you want to use Cursor IDE with ChatGPT for coding tasks:

1. Get your API key from .env (if stored there):

``bash grep OPENAI_API_KEY .env ``

1. Configure in Cursor:

• Open Cursor Settings (Cmd+Shift+J / Ctrl+Shift+J)
• Navigate to Models section
• Paste your OpenAI API key and verify
• Select your preferred GPT model (GPT-4, GPT-4 Turbo, etc.)

> Note: Cursor requires the API key to be entered in its settings UI - it doesn't automatically read from .env files. Copy the value from your .env file and paste it into Cursor's settings.

This gives you ChatGPT-powered AI in Cursor with persistent system prompts and full codebase integration. See [CURSORSETUP.md](CURSORSETUP.md) for complete setup instructions.

System Prompt:

For better LLM interactions, you can configure a system prompt:

• In MCP Jam: Copy the content from system_prompt.txt into the system prompt field in the Playground tab when starting a new session.
• In Cursor IDE: Set the system prompt in Cursor's settings (persists between sessions) - see [CURSORSETUP.md](CURSORSETUP.md) for details.
• Via Tool: Use the get_system_prompt tool in either interface to retrieve the prompt text automatically.

> Note: MCP Jam Guest Mode may not persist system prompts between sessions. Cursor IDE settings persist. Keep system_prompt.txt handy or use the get_system_prompt tool for quick access.

MCP Jam Features:

• ✅ Guest Mode: No account required - start testing immediately
• ✅ Beautiful UI: Modern interface with AI provider logos
• ✅ Easy Setup: Simple server configuration with clear forms
• ✅ Real-time Testing: Interactive tool execution with immediate results
• ✅ Full Functionality: Access to all DICOM, FHIR, RIS, and reporting tools
• ✅ LLM Playground: Test your DICOM server with various LLMs
• ✅ Community Driven: Active development with regular updates

Note on Resources: Resources are registered with FastMCP and accessible via:

• Tools (works in Guest Mode): Use list_saved_resources and get_saved_resource tools to access resources
• Resources Panel (may require account): Native MCP resources protocol - visible in Resources tab if supported by your MCP Jam mode

MCP Jam Tabs:

• Servers Tab: Manage and connect to your DICOM MCP server
• Tools Tab: Browse and test all available tools interactively
• Playground Tab: Chat with your DICOM server using configured LLMs
• Settings Tab: Configure API keys and LLM providers

Available DICOM Tools:

• verify_connection - Test DICOM connectivity
• list_dicom_nodes - Show configured servers
• query_patients - Search for patients
• query_studies - Find studies by criteria
• query_series - Locate series within studies
• query_instances - Find individual DICOM images
• extract_pdf_text_from_dicom - Extract text from DICOM PDFs
• move_series / move_study - Transfer DICOM data
• switch_dicom_node - Change active server
• get_attribute_presets - Show query detail levels

Available FHIR Tools (when FHIR is configured):

• verify_fhir_connection - Test FHIR server connectivity
• list_fhir_servers - List configured FHIR servers
• switch_fhir_server - Switch to a different FHIR server without restarting
• fhir_search_patient - Search for Patient resources
• fhir_search_imaging_study - Search for ImagingStudy resources
• fhir_read_resource - Read any FHIR resource by type and ID
• fhir_create_resource - Create new FHIR resources (Patient, ImagingStudy, ServiceRequest, etc.)
• fhir_update_resource - Update existing FHIR resources

See [FHIRSERVERS.md](FHIRSERVERS.md) for configuration details.

Mini-RIS Tools (when MySQL is configured):

• list_mini_ris_patients - Browse patient demographics stored in the mini-RIS schema (filter by MRN or name)
• create_mwl_from_order - Create a DICOM Modality Worklist entry from an existing mini-RIS order
• create_synthetic_cr_study - Generate synthetic CR DICOM images and send to PACS (virtual modality)

Radiology Reporting Tools (when MySQL is configured):

• get_study_for_report - Retrieve complete study information for radiology reporting
• list_radiologists - List available radiologists with credentials
• create_radiology_report - Create structured radiology report with findings and impression
• generate_report_pdf - Generate professional PDF from report (base64 encoded)
• attach_report_to_pacs - Upload report PDF to PACS as DICOM Encapsulated PDF

Mini-RIS Database Schema:

The mini_ris.sql schema provides a complete radiology information system with:

• Core Entities: Patients, Providers, Encounters, Orders, Imaging Studies, Reports
• Reference Tables:
• dicom_tags - 50 essential DICOM tag definitions for MWL/MPPS validation
• procedures - 14 CR/XR procedure codes with typical views and image counts
• modalities - Standard DICOM modality codes
• body_parts - Anatomical regions for imaging
• MWL/MPPS Support: Tables for Modality Worklist and Modality Performed Procedure Step tracking

MCP Naming Scheme:

All data in the mini-RIS uses a consistent "MCP-" prefix/suffix naming scheme to clearly mark it as development/synthetic data:

• MRNs: MCP-MRN-0001
• Accession Numbers: MCP-ACC-2025-0001
• Patient Names: Johnson-MCP^Alex (DICOM format)
• Physician Names: MCP-Emily^Chen (DICOM format)

See [MCPNAMINGSCHEME.md](MCPNAMINGSCHEME.md) for complete details.

Setup:

1. Launch the MySQL service:

``bash docker compose up -d mysql ``

1. Initialize the database (automatic on first start, or manually):

```bash docker exec -i dicom-mcp-mysql-1 mysql -uorthancrisapp -porthancrisapp orthanc_ris **

Features:

• ✅ LLM-Powered Chat - Intelligent chat with OpenAI integration for natural language queries
• ✅ Tool Browser - Browse and explore all 28 available DICOM/FHIR/RIS tools
• ✅ Prompt Management - Edit and save system prompts optimized for medical imaging
• ✅ Tool Execution - Execute tools directly from chat or UI
• ✅ Medical Imaging Focus - Customized for DICOM and FHIR workflows
• ✅ Self-Contained - Everything in your repo, no external services needed
• ✅ Dark Theme - Beautiful, modern dark UI
• ✅ Saved Resources - Curated reference files (e.g., Orthanc OpenAPI) live in resources/manifest.yaml, accessible via the Resources panel or new list_saved_resources / get_saved_resource MCP tools.

LLM Integration:

Enable OpenAI-powered chat by setting your API key:

export OPENAI_API_KEY="your-api-key-here"

The LLM will:

• Understand natural language queries about medical imaging
• Automatically select and execute appropriate DICOM/FHIR tools
• Format results in a clinical, readable format
• Use the medical imaging system prompt for context-aware responses

Example Queries:

• "List all available DICOM nodes"
• "Find patients with last name Smith"
• "Show me studies from last week"
• "Verify connection to PACS"
• "What tools are available for FHIR?"

🙏 Acknowledgments

• Built using FastMCP - The fast, Pythonic way to build MCP servers
• Built using pynetdicom for DICOM network communication
• Uses pypdf for PDF text extraction

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sscotti
• Source: sscotti/dicom-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.