DICOM-MCP

Instructions

Implementation Reference

• src/dicom_mcp/server.py:258-279 (handler)

  MCP tool handler for 'scan-dicom-directory': validates directory, calls scan_directory helper, stores series in global state, notifies clients of resource changes, and returns summary of found series.

  elif name == "scan-dicom-directory":
      directory = arguments.get("directory")
      if not directory or not os.path.isdir(directory):
          raise ValueError(f"Invalid directory: {directory}")
          
      # Scan the directory for DICOM files
      series_list = scan_directory(directory)
      
      # Update state with found series
      for series in series_list:
          dicom_data[series.series_uid] = series
          
      # Notify clients that resources have changed
      await server.request_context.session.send_resource_list_changed()
      
      return [
          types.TextContent(
              type="text",
              text=f"Found {len(series_list)} DICOM series in {directory}:\n" + 
                   "\n".join([f"- {s.modality or 'Unknown'}: {s.description or s.series_uid} ({s.file_count} files)" for s in series_list])
          )
      ]

• src/dicom_mcp/server.py:166-176 (registration)

  Registration of the 'scan-dicom-directory' tool in handle_list_tools(), including description and JSON input schema requiring 'directory' path.

  types.Tool(
      name="scan-dicom-directory",
      description="Scan a directory for DICOM files and organize them into series",
      inputSchema={
          "type": "object",
          "properties": {
              "directory": {"type": "string", "description": "Path to directory containing DICOM files"},
          },
          "required": ["directory"],
      },
  ),

• src/dicom_mcp/dicom_tools.py:38-47 (schema)

  Pydantic model (schema) for DicomSeries used as return type for scan_directory and stored in server state.

  class DicomSeries(BaseModel):
      """Model representing a DICOM series"""
      series_uid: str
      study_uid: Optional[str] = None
      modality: str
      description: Optional[str] = None
      path: str
      file_count: int
      patient_id: Optional[str] = None

• src/dicom_mcp/dicom_tools.py:73-116 (helper)

  Core helper function that scans directory recursively for DICOM files using glob and pydicom, groups by SeriesInstanceUID, extracts metadata, and returns list of DicomSeries objects.

  def scan_directory(directory: str) -> List[DicomSeries]:
      """Scan a directory for DICOM files and organize them into series"""
      series_dict = {}
      
      # Find all DICOM files (recursively if needed)
      dicom_files = []
      for ext in [".dcm", ".DCM", ""]:  # Empty string for no extension files
          dicom_files.extend(glob.glob(os.path.join(directory, f"**/*{ext}"), recursive=True))
      
      for file_path in dicom_files:
          try:
              ds = pydicom.dcmread(file_path, stop_before_pixels=True)
              series_uid = ds.SeriesInstanceUID
              
              if series_uid not in series_dict:
                  series_dict[series_uid] = {
                      "files": [],
                      "study_uid": getattr(ds, "StudyInstanceUID", None),
                      "modality": getattr(ds, "Modality", "Unknown"),
                      "description": getattr(ds, "SeriesDescription", None),
                      "patient_id": getattr(ds, "PatientID", None)
                  }
              
              series_dict[series_uid]["files"].append(file_path)
          except Exception as e:
              print(f"Error reading {file_path}: {e}")
      
      # Convert to DicomSeries objects
      result = []
      for series_uid, data in series_dict.items():
          # Use the directory of the first file as the series path
          series_path = os.path.dirname(data["files"][0]) if data["files"] else ""
          
          result.append(DicomSeries(
              series_uid=series_uid,
              study_uid=data["study_uid"],
              modality=data["modality"],
              description=data["description"],
              path=series_path,
              file_count=len(data["files"]),
              patient_id=data["patient_id"]
          ))
      
      return result