PCILeech용 MCP 서버

English | 中文

English

DMA 기반 메모리 작업을 위해 PCILeech에 표준화된 인터페이스를 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이를 통해 MCP 클라이언트(예: Claude Code)는 도구 호출을 통해 메모리/디버그 워크플로우를 수행할 수 있습니다.

저자: EVAN & MOER 지원: Discord 참여하기

Related MCP server: Volatility MCP

기능

• 19개의 MCP 도구 (기능별 그룹화):

  • 코어 메모리: memory_read, memory_write, memory_format

  • 시스템: system_info, memory_probe, memory_dump, memory_search, memory_patch, process_list

  • 주소 변환: translate_phys2virt, translate_virt2phys, process_virt2phys

  • 커널 모듈 (KMD): kmd_load, kmd_exit, kmd_execute, kmd_list_scripts

  • 고급/FPGA: benchmark, tlp_send, fpga_config

• 가상 주소 모드: 메모리 도구는 pid 또는 process_name을 지원합니다 (상호 배타적).

• 비차단 서버: PCILeech 호출은 asyncio.to_thread를 통해 실행됩니다.

• 출력 도우미: 분석을 위한 hexdump + ASCII + byte/DWORD 뷰

사전 요구 사항

• Windows 10/11 (x64)

• Python 3.10+

• PCILeech 하드웨어 (올바르게 구성 및 작동 중)

• PCILeech 바이너리 (pcileech/ 하위에 번들됨)

빠른 시작

1. 복제

git clone https://github.com/Evan7198/mcp_server_pcileech
cd mcp_server_pcileech
// download release in https://github.com/ufrisk/pcileech for using the latest pcileech

2. 의존성 설치

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

MCP 가져오기/버전 문제가 발생하면 대신 pyproject.toml에서 설치하세요:

pip install -e .

3. PCILeech 확인

cd pcileech
pcileech.exe probe

4. Claude Code (MCP) 구성

서버 항목을 추가합니다 (경로 조정):

"mcpServers": {
  "pcileech": {
    "command": "C:\\path\\to\\mcp_server_pcileech\\.venv\\Scripts\\python.exe",
    "args": [
      "C:\\path\\to\\mcp_server_pcileech\\main.py"
    ],
    "cwd": "C:\\path\\to\\mcp_server_pcileech",
    "env": {}
  }
}

MCP 구성을 편집한 후 Claude Code를 다시 시작하세요.

구성

config.json은 PCILeech 실행 파일 경로와 타임아웃을 제어합니다:

{
  "pcileech": {
    "executable_path": "pcileech\\pcileech.exe",
    "timeout_seconds": 30
  },
  "server": {
    "name": "mcp-server-pcileech",
    "version": "1.0.0"
  }
}

사용 예시

구성이 완료되면 자연어로 작업을 요청할 수 있으며, 클라이언트가 이를 도구 호출로 변환합니다:

Read 256 bytes from address 0x1000

Write the hex data 48656c6c6f to address 0x2000

Show me a formatted view of 64 bytes at address 0x1000

MCP 도구 (개요)

참고:

• 가상 메모리 모드: 메모리 도구의 경우 pid 또는 process_name을 사용하세요 (둘 다 사용 불가).

• FPGA 전용: 일부 작업은 FPGA 기반 장치가 필요합니다 (예: memory_probe, tlp_send).

코어 메모리

• memory_read(address, length, pid?, process_name?) → 16진수 데이터 + 메타데이터

• memory_write(address, data, pid?, process_name?) → 성공/확인

• memory_format(address, length, formats?, pid?, process_name?) → hexdump/ASCII/배열/raw

시스템

• system_info(verbose?) → 대상 시스템 + 장치 정보

• memory_probe(min_address?, max_address?) → 읽기 가능한 영역 (FPGA 전용)

• memory_dump(min_address, max_address, output_file?, force?) → 덤프 파일 경로/결과

• memory_search(pattern? | signature?, min_address?, max_address?, find_all?) → 일치 항목

• memory_patch(signature, min_address?, max_address?, patch_all?) → 패치 결과

• process_list() → PID/PPID/이름 목록

주소 변환

• translate_phys2virt(physical_address, cr3) → 변환 세부 정보

• translate_virt2phys(virtual_address, cr3) → 변환 세부 정보

• process_virt2phys(pid, virtual_address) → 변환 세부 정보

커널 모듈 (KMD)

• kmd_load(kmd_type, use_pt?, cr3?) → 로드 결과 (+ KMD 주소 캐시)

• kmd_exit(kmd_address?) → 언로드 결과 (생략 시 캐시된 주소 사용)

• kmd_execute(script_name, kmd_address?, input_file?, output_file?, parameter_string?, parameter_int0?, parameter_int1?)

• kmd_list_scripts(platform?) → 플랫폼별로 그룹화된 사용 가능한 .ksh 스크립트

고급 / FPGA

• benchmark(test_type?, address?) → MB/s 결과 (하드웨어에 따라 다름)

• tlp_send(tlp_data?, wait_seconds?, verbose?) → 전송/수신된 TLP (FPGA 전용)

• fpga_config(action?, address?, data?, output_file?) → 구성 읽기/쓰기 (FPGA 전용)

아키텍처

2계층 설계

1. MCP 서버 계층 (main.py)

   • Stdio 전송, 도구 스키마, 유효성 검사, 포맷팅

   • 이벤트 루프 차단을 방지하기 위해 asyncio.to_thread() 사용

2. PCILeech 래퍼 (pcileech_wrapper.py)

   • pcileech.exe에 대한 하위 프로세스 호출

   • 주소 정렬 + 256바이트 청킹 (PCILeech display 동작)

   • 출력 파싱, 타임아웃 및 오류 매핑

문제 해결

PCILeech를 찾을 수 없음

오류: PCILeech executable not found 해결: config.json → pcileech.executable_path 확인

하드웨어가 연결되지 않음

경고: PCILeech connection verification failed 해결: pcileech\pcileech.exe probe를 실행하고 드라이버/케이블 연결 확인

메모리 액세스 실패

오류: Memory read/write failed 해결: CLI에서 먼저 주소/범위를 확인한 후 MCP를 통해 다시 시도

타임아웃

오류: PCILeech command timed out 해결: config.json에서 pcileech.timeout_seconds 증가

프로젝트 구조

mcp_server_pcileech/
├── main.py
├── pcileech_wrapper.py
├── config.json
├── pyproject.toml
├── requirements.txt
├── README.md
├── README_CN.md
└── pcileech/
    ├── pcileech.exe
    └── LICENSE.txt

제한 사항

• Windows 전용 (이 저장소의 PCILeech는 Windows 중심)

• 실제 메모리 작업을 위해 호환되는 PCILeech 하드웨어 필요

• 읽기 크기 제한:

  • memory_read: 최대 1MB

  • memory_format: 최대 4KB (읽기 가능한 출력)

• 일부 도구는 FPGA 전용 (probe/TLP/config)

• PCILeech 명령은 순차적으로 실행됨 (하위 프로세스 호출당)

보안 및 법적 고지

이 도구는 승인된 디버깅/보안 연구/교육용으로 제작되었습니다. 무단 액세스나 악의적인 활동에 사용하지 마십시오. 귀하는 관련 법률 및 규정을 준수할 책임이 있습니다.

라이선스

이 프로젝트는 자체 라이선스가 있는 PCILeech를 래핑합니다. pcileech/LICENSE.txt를 참조하세요.

크레딧

• PCILeech: Ulf Frisk

• Model Context Protocol: Anthropic

• 저자: EVAN & MOER

버전

이 저장소의 도구 세트에는 현재 19개의 도구 확장 세트가 포함되어 있습니다. 패키지/구성 버전은 다음을 참조하세요:

• pyproject.toml ([project].version)

• config.json (server.version)

지원

• Discord: Discord 참여하기

• 이슈: 이 저장소에 이슈 열기

• PCILeech 문서: PCILeech GitHub

• MCP 문서: MCP 문서

변경 로그

v1.0.0 (2025-12-16)

• 전체 PCILeech 기능을 다루는 19개의 MCP 도구로 확장

• 메모리 도구에 가상 주소 모드(pid / process_name) 추가

• 주소 변환, KMD 및 FPGA/고급 도구 추가

• 더 광범위한 유효성 검사 및 오류 처리 추가; 비차단 서버 실행

v0.1.0 (2025-12-10)

• 초기 릴리스

• 3개의 MCP 도구: memory_read, memory_write, memory_format