PCILeech용 MCP 서버

English

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

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

기능

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계층 설계

MCP 서버 계층 (main.py)
- Stdio 전송, 도구 스키마, 유효성 검사, 포맷팅
- 이벤트 루프 차단을 방지하기 위해 asyncio.to_thread() 사용
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

PCILeech MCP Server