berkdurmus/mcp-dicom-server

MCP DICOM Server

A Model Context Protocol (MCP) server for handling DICOM (Digital Imaging and Communications in Medicine) files. This server provides tools for AI assistants to read, analyze, manipulate, and convert medical imaging files.

Features

• Metadata Extraction: Extract patient information, study details, and image parameters from DICOM files
• Tag Management: View and search all DICOM tags and their values
• Image Conversion: Convert DICOM images to PNG format with proper window/level adjustments
• Multi-frame Support: Extract specific frames from multi-frame DICOM files
• Anonymization: Remove patient identifying information from DICOM files
• Batch Processing: Process multiple DICOM files in a directory
• Structured Output: Returns data in structured format with reasoning, items array, and text [[memory:2966621]]

Installation

1. Clone the repository:

git clone https://github.com/berkdurmus/mcp-dicom-server.git
cd mcp-dicom-server

2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

Usage

Running the Server

The MCP DICOM server can be run in stdio mode for integration with AI assistants:

npm start

For development with auto-reload:

npm run dev

Available Tools

The server provides the following tools:

1. dicom_extract_metadata

Extract comprehensive metadata from a DICOM file including patient information, study details, and image parameters.

Parameters:

• filePath (string): Path to the DICOM file

Returns: Patient name, ID, study date/time, modality, image dimensions, pixel spacing, window settings, and more.

2. dicom_get_all_tags

Retrieve all DICOM tags and their values from a file.

Parameters:

• filePath (string): Path to the DICOM file

Returns: Array of all DICOM tags with their values and descriptions.

3. dicom_search_tags

Search for specific DICOM tags by keyword.

Parameters:

• filePath (string): Path to the DICOM file
• keyword (string): Keyword to search for in tags

Returns: Filtered array of matching DICOM tags.

4. dicom_convert_to_png

Convert a DICOM image to PNG format with proper window/level adjustments.

Parameters:

• dicomPath (string): Path to the input DICOM file
• outputPath (string): Path for the output PNG file

Returns: Success status with output file path.

5. dicom_extract_frame

Extract a specific frame from a multi-frame DICOM file.

Parameters:

• dicomPath (string): Path to the multi-frame DICOM file
• frameNumber (number): Frame number to extract (0-based)
• outputPath (string): Path for the output PNG file

Returns: Success status with extracted frame details.

6. dicom_anonymize

Anonymize a DICOM file by removing patient identifying information.

Parameters:

• inputPath (string): Path to the input DICOM file
• outputPath (string): Path for the anonymized DICOM file

Returns: Success status with anonymized file path.

7. dicom_list_files

List all DICOM files in a directory recursively.

Parameters:

• directory (string): Directory path to search for DICOM files

Returns: Array of DICOM file paths found.

8. dicom_batch_extract_metadata

Extract metadata from all DICOM files in a directory.

Parameters:

• directory (string): Directory path containing DICOM files

Returns: Array of metadata extraction results for each file.

Integration with Claude Desktop

To use this MCP server with Claude Desktop, add the following to your Claude Desktop configuration:

1. Open Claude Desktop settings
2. Navigate to Developer -> MCP Settings
3. Add the server configuration:

{
  "mcpServers": {
    "dicom": {
      "command": "node",
      "args": ["/path/to/mcp-dicom-server/dist/index.js"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Project Structure

mcp-dicom-server/
├── src/
│   ├── index.ts              # MCP server implementation
│   └── services/
│       └── dicom.service.ts  # DICOM processing service [[memory:2966615]]
├── dist/                      # Compiled JavaScript output
├── package.json              # Project dependencies
├── tsconfig.json            # TypeScript configuration
└── README.md                # This file

Output Format

All tools return structured output following this format [[memory:2966621]]:

{
  "reasoning": "Explanation of what was done",
  "items": [
    // Array of result items
  ],
  "text": "Human-readable summary"
}

Dependencies

• @modelcontextprotocol/sdk: MCP SDK for server implementation
• dicom-parser: Low-level DICOM file parsing
• dcmjs: High-level DICOM manipulation
• sharp: Image processing for PNG conversion
• pino: Structured logging

Environment Variables

• LOG_LEVEL: Set logging level (debug, info, warn, error)

Security Considerations

• The anonymization feature removes common patient identifiers but may not remove all PHI
• Always verify anonymization results before sharing DICOM files
• Be cautious when processing files from untrusted sources
• The server operates on local files only and doesn't expose network endpoints

Limitations

• PNG conversion applies basic window/level adjustments and may not perfectly replicate DICOM viewer rendering
• Multi-frame extraction currently supports basic frame extraction
• Some proprietary DICOM tags may not be fully supported

Contributing

Contributions are welcome! Please submit pull requests or open issues for bugs and feature requests.

License

MIT