dicom-mcp: DICOM 모델 컨텍스트 프로토콜 서버

이 저장소는 블로그 게시물의 일부입니다: Agentic Healthcare LLMs

개요

DICOM(의료 디지털 영상 및 통신) 상호작용을 위한 모델 컨텍스트 프로토콜 서버입니다. 이 서버는 DICOM 서버에 쿼리하고 상호작용하는 도구를 제공하여 대용량 언어 모델이 의료 영상 메타데이터에 접근하고 분석할 수 있도록 지원합니다.

dicom-mcp는 AI 어시스턴트가 표준 DICOM 네트워킹 프로토콜을 사용하여 DICOM 서버에서 환자 정보, 연구, 시리즈 및 인스턴스를 쿼리할 수 있도록 지원합니다. 또한 DICOM 형식으로 저장된 캡슐화된 PDF 문서에서 텍스트를 추출하여 임상 보고서를 분석할 수 있도록 지원합니다. pynetdicom을 기반으로 하며 모델 컨텍스트 프로토콜(Model Context Protocol) 사양을 따릅니다.

도구

list_dicom_nodes
- 구성된 모든 DICOM 노드와 호출 AE 제목을 나열합니다.
- 입력: 없음
- 반환: 현재 노드, 사용 가능한 노드, 현재 호출 AE 제목 및 사용 가능한 호출 AE 제목
switch_dicom_node
- 다른 구성된 DICOM 노드로 전환
- 입력:
  - node_name (문자열): 전환할 노드의 이름
- 반환: 성공 메시지
switch_calling_aet
- 다른 구성된 호출 AE 제목으로 전환합니다.
- 입력:
  - aet_name (문자열): 전환할 호출 AE 제목의 이름
- 반환: 성공 메시지
verify_connection
- C-ECHO를 사용하여 구성된 DICOM 노드에 대한 연결을 테스트합니다.
- 입력: 없음
- 반환: 세부 정보가 포함된 성공 또는 실패 메시지
query_patients
- 지정된 기준과 일치하는 환자 검색
- 입력:
  - name_pattern (문자열, 선택 사항): 환자 이름 패턴(와일드카드 포함 가능)
  - patient_id (문자열, 선택 사항): 환자 ID
  - birth_date (문자열, 선택 사항): 환자 생년월일(YYYYMMDD)
  - attribute_preset (문자열, 선택 사항): 세부 정보의 사전 설정 수준(최소, 표준, 확장)
  - additional_attributes (string[], 선택 사항): 포함할 추가 DICOM 속성
  - exclude_attributes (문자열[], 선택 사항): 제외할 DICOM 속성
- 반환: 일치하는 환자 기록 배열
query_studies
- 지정된 기준과 일치하는 연구 검색
- 입력:
  - patient_id (문자열, 선택 사항): 환자 ID
  - study_date (문자열, 선택 사항): 연구 날짜 또는 범위(YYYYMMDD 또는 YYYYMMDD-YYYYMMDD)
  - modality_in_study (문자열, 선택 사항): 연구 모달리티
  - study_description (문자열, 선택 사항): 연구 설명(와일드카드 포함 가능)
  - accession_number (문자열, 선택 사항): 가입 번호
  - study_instance_uid (문자열, 선택 사항): 연구 인스턴스 UID
  - attribute_preset (문자열, 선택 사항): 세부 정보의 사전 설정 수준
  - additional_attributes (string[], 선택 사항): 포함할 추가 DICOM 속성
  - exclude_attributes (문자열[], 선택 사항): 제외할 DICOM 속성
- 반환: 일치하는 연구 기록 배열
query_series
- 연구 내 시리즈 검색
- 입력:
  - study_instance_uid (문자열): 연구 인스턴스 UID(필수)
  - modality (문자열, 선택 사항): 모달리티(예: "CT", "MR")
  - series_number (문자열, 선택 사항): 시리즈 번호
  - series_description (문자열, 선택 사항): 시리즈 설명
  - series_instance_uid (문자열, 선택 사항): 시리즈 인스턴스 UID
  - attribute_preset (문자열, 선택 사항): 세부 정보의 사전 설정 수준
  - additional_attributes (string[], 선택 사항): 포함할 추가 DICOM 속성
  - exclude_attributes (문자열[], 선택 사항): 제외할 DICOM 속성
- 반환: 일치하는 시리즈 레코드 배열
query_instances
- 시리즈 내에서 인스턴스 검색
- 입력:
  - series_instance_uid (문자열): 시리즈 인스턴스 UID(필수)
  - instance_number (문자열, 선택 사항): 인스턴스 번호
  - sop_instance_uid (문자열, 선택 사항): SOP 인스턴스 UID
  - attribute_preset (문자열, 선택 사항): 세부 정보의 사전 설정 수준
  - additional_attributes (string[], 선택 사항): 포함할 추가 DICOM 속성
  - exclude_attributes (문자열[], 선택 사항): 제외할 DICOM 속성
- 반환: 일치하는 인스턴스 레코드 배열
get_attribute_presets
- 쿼리에 사용 가능한 속성 사전 설정을 나열합니다.
- 입력: 없음
- 반환: 레벨별 사용 가능한 사전 설정 및 해당 속성 사전
retrieve_instance

특정 DICOM 인스턴스를 검색하여 로컬 파일 시스템에 저장합니다.
입력:
- study_instance_uid (문자열): 연구 인스턴스 UID
- series_instance_uid (문자열): 시리즈 인스턴스 UID
- sop_instance_uid (문자열): SOP 인스턴스 UID
- output_directory (문자열, 선택 사항): 검색된 인스턴스를 저장할 디렉토리(기본값: "./retrieved_files")
반환: 검색 작업에 대한 정보가 포함된 사전

extract_pdf_text_from_dicom

캡슐화된 PDF를 포함하는 DICOM 인스턴스를 검색하고 해당 텍스트 콘텐츠를 추출합니다.
입력:
- study_instance_uid (문자열): 연구 인스턴스 UID
- series_instance_uid (문자열): 시리즈 인스턴스 UID
- sop_instance_uid (문자열): SOP 인스턴스 UID
반환: 추출된 텍스트 정보 및 상태가 포함된 사전

설치

필수 조건

Python 3.12 이상
연결할 DICOM 서버(예: Orthanc, dcm4chee 등)

pip 사용하기

pip를 통해 설치:

지엑스피1

구성

dicom-mcp에는 DICOM 노드와 호출 AE 제목을 정의하는 YAML 구성 파일이 필요합니다. 다음 구조의 구성 파일을 생성하세요.

# DICOM nodes configuration
nodes:
  orthanc:
    host: "localhost"
    port: 4242
    ae_title: "ORTHANC"
    description: "Local Orthanc DICOM server"
  
  clinical:
    host: "pacs.hospital.org"
    port: 11112
    ae_title: "CLIN_PACS"
    description: "Clinical PACS server"

# Local calling AE titles
calling_aets:
  default:
    ae_title: "MCPSCU"
    description: "Default calling AE title"
  
  modality:
    ae_title: "MODALITY"
    description: "Simulating a modality"

# Currently selected node
current_node: "orthanc"

# Currently selected calling AE title
current_calling_aet: "default"

용법

명령줄

스크립트 진입점을 사용하여 서버를 실행합니다.

dicom-mcp /path/to/configuration.yaml

uv를 사용하는 경우:

uv run dicom-mcp /path/to/configuration.yaml

Claude Desktop을 사용한 구성

claude_desktop_config.json 에 다음을 추가하세요:

"mcpServers": {
  "dicom": {
    "command": "uv",
    "args": ["--directory", "/path/to/dicom-mcp", "run", "dicom-mcp", "/path/to/configuration.yaml"]
  }
}

Zed와 함께 사용

Zed settings.json에 다음을 추가합니다.

"context_servers": [
  "dicom-mcp": {
    "command": {
      "path": "uv",
      "args": ["--directory", "/path/to/dicom-mcp", "run", "dicom-mcp", "/path/to/configuration.yaml"]
    }
  }
],

예제 쿼리

사용 가능한 DICOM 노드 나열

list_dicom_nodes()

다른 노드로 전환

switch_dicom_node(node_name="clinical")

다른 호출 AE 제목으로 전환

switch_calling_aet(aet_name="modality")

연결 확인

verify_connection()

환자 검색

# Search by name pattern (using wildcard)
patients = query_patients(name_pattern="SMITH*")

# Search by patient ID
patients = query_patients(patient_id="12345678")

# Get detailed information
patients = query_patients(patient_id="12345678", attribute_preset="extended")

연구 검색

# Find all studies for a patient
studies = query_studies(patient_id="12345678")

# Find studies within a date range
studies = query_studies(study_date="20230101-20231231")

# Find studies by modality
studies = query_studies(modality_in_study="CT")

연구에서 시리즈 검색

# Find all series in a study
series = query_series(study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1")

# Find series by modality and description
series = query_series(
    study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1",
    modality="CT",
    series_description="CHEST*"
)

시리즈에서 인스턴스 검색

# Find all instances in a series
instances = query_instances(series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2")

# Find a specific instance by number
instances = query_instances(
    series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2",
    instance_number="1"
)

DICOM 인스턴스 검색

# Retrieve a specific instance
result = retrieve_instance(
    study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1",
    series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2",
    sop_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.3",
    output_directory="./dicom_files"
)

DICOM 캡슐화된 PDF에서 텍스트 추출

# Extract text from an encapsulated PDF
result = extract_pdf_text_from_dicom(
    study_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.1",
    series_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.2",
    sop_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.3"
)

디버깅

MCP 검사기를 사용하여 서버를 디버깅할 수 있습니다.

npx @modelcontextprotocol/inspector uv --directory /path/to/dicom-mcp run dicom-mcp /path/to/configuration.yaml

개발

개발 환경 설정

저장소를 복제합니다.
git clone https://github.com/yourusername/dicom-mcp.git cd dicom-mcp
가상 환경 만들기:
python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate
종속성 설치:
pip install -e .

테스트 실행

테스트를 실행하려면 Orthanc 서버가 필요합니다. Docker를 사용하여 서버를 시작할 수 있습니다.

cd tests
docker-compose up -d

그런 다음 테스트를 실행합니다.

pytest tests/test_dicom_mcp.py

PDF 추출 기능을 테스트하려면:

pytest tests/test_dicom_pdf.py

프로젝트 구조

src/dicom_mcp/ : 메인 패키지
- __init__.py : 패키지 초기화
- __main__.py : 진입점
- server.py : MCP 서버 구현
- dicom_client.py : DICOM 클라이언트 구현
- attributes.py : DICOM 속성 사전 설정
- config.py : Pydantic을 사용한 구성 관리

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

감사의 말

pynetdicom 기반으로 구축됨
모델 컨텍스트 프로토콜 사양을 따릅니다.
PDF 텍스트 추출을 위해 PyPDF2를 사용합니다.

DICOM MCP Server

Integrations