MCP-Server für PCILeech

Englisch

Ein Model Context Protocol (MCP)-Server, der eine standardisierte Schnittstelle zu PCILeech für DMA-basierte Speicheroperationen bereitstellt. Dies ermöglicht es MCP-Clients (z. B. Claude Code), Speicher-/Debug-Workflows durch Tool-Aufrufe auszuführen.

Autoren: EVAN & MOER Support: Tritt unserem Discord bei

Funktionen

19 MCP-Tools, gruppiert nach Fähigkeiten:
- Kernspeicher: memory_read, memory_write, memory_format
- System: system_info, memory_probe, memory_dump, memory_search, memory_patch, process_list
- Adressübersetzung: translate_phys2virt, translate_virt2phys, process_virt2phys
- Kernel-Modul (KMD): kmd_load, kmd_exit, kmd_execute, kmd_list_scripts
- Erweitert/FPGA: benchmark, tlp_send, fpga_config
Virtueller Adressmodus: Speicher-Tools unterstützen pid oder process_name (schließen sich gegenseitig aus)
Nicht-blockierender Server: PCILeech-Aufrufe werden über asyncio.to_thread ausgeführt
Ausgabe-Helfer: Hexdump + ASCII + Byte/DWORD-Ansichten zur Analyse

Voraussetzungen

Windows 10/11 (x64)
Python 3.10+
PCILeech-Hardware korrekt konfiguriert und funktionsfähig
PCILeech-Binärdateien (gebündelt unter pcileech/)

Schnellstart

1. Klonen

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. Abhängigkeiten installieren

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

Falls Probleme mit dem MCP-Import oder der Version auftreten, installieren Sie stattdessen über pyproject.toml:

pip install -e .

3. PCILeech verifizieren

cd pcileech
pcileech.exe probe

4. Claude Code (MCP) konfigurieren

Fügen Sie einen Servereintrag hinzu (Pfade anpassen):

"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": {}
  }
}

Starten Sie Claude Code nach dem Bearbeiten der MCP-Konfiguration neu.

Konfiguration

config.json steuert den Pfad zur PCILeech-Executable und die Timeouts:

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

Anwendungsbeispiele

Sobald konfiguriert, können Sie Aktionen in natürlicher Sprache anfordern; der Client übersetzt diese in Tool-Aufrufe:

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-Tools (Übersicht)

Hinweise:

Virtueller Speichermodus: Verwenden Sie für Speicher-Tools pid oder process_name (nicht beides).
Nur FPGA: Einige Operationen erfordern ein FPGA-basiertes Gerät (z. B. memory_probe, tlp_send).

Kernspeicher

memory_read(address, length, pid?, process_name?) → Hex-Daten + Metadaten
memory_write(address, data, pid?, process_name?) → Erfolg/Bestätigung
memory_format(address, length, formats?, pid?, process_name?) → Hexdump/ASCII/Arrays/Raw

System

system_info(verbose?) → Zielsystem + Geräteinformationen
memory_probe(min_address?, max_address?) → lesbare Bereiche (nur FPGA)
memory_dump(min_address, max_address, output_file?, force?) → Dump-Dateipfad/Ergebnis
memory_search(pattern? | signature?, min_address?, max_address?, find_all?) → Übereinstimmungen
memory_patch(signature, min_address?, max_address?, patch_all?) → Patch-Ergebnis
process_list() → PID/PPID/Namensliste

Adressübersetzung

translate_phys2virt(physical_address, cr3) → Übersetzungsdetails
translate_virt2phys(virtual_address, cr3) → Übersetzungsdetails
process_virt2phys(pid, virtual_address) → Übersetzungsdetails

Kernel-Modul (KMD)

kmd_load(kmd_type, use_pt?, cr3?) → Ladeergebnis (+ speichert KMD-Adresse im Cache)
kmd_exit(kmd_address?) → Entladeergebnis (verwendet zwischengespeicherte Adresse, falls weggelassen)
kmd_execute(script_name, kmd_address?, input_file?, output_file?, parameter_string?, parameter_int0?, parameter_int1?)
kmd_list_scripts(platform?) → verfügbare .ksh-Skripte, gruppiert nach Plattform

Erweitert / FPGA

benchmark(test_type?, address?) → MB/s-Ergebnisse (abhängig von der Hardware)
tlp_send(tlp_data?, wait_seconds?, verbose?) → gesendete/empfangene TLPs (nur FPGA)
fpga_config(action?, address?, data?, output_file?) → Konfiguration lesen/schreiben (nur FPGA)

Architektur

Zwei-Schichten-Design

MCP-Server-Schicht (main.py)
- Stdio-Transport, Tool-Schemas, Validierung, Formatierung
- Verwendet asyncio.to_thread(), um den Event-Loop nicht zu blockieren
PCILeech-Wrapper (pcileech_wrapper.py)
- Subprozess-Aufrufe an pcileech.exe
- Adressausrichtung + 256-Byte-Chunking (PCILeech display-Verhalten)
- Ausgabeparsing, Timeouts und Fehlerzuordnung

Fehlerbehebung

PCILeech nicht gefunden

Fehler: PCILeech executable not found Lösung: Überprüfen Sie config.json → pcileech.executable_path

Hardware nicht verbunden

Warnung: PCILeech connection verification failed Lösung: Führen Sie pcileech\pcileech.exe probe aus und überprüfen Sie Treiber/Verkabelung

Speicherzugriff schlägt fehl

Fehler: Memory read/write failed Lösung: Überprüfen Sie zuerst die Adresse/den Bereich über die CLI und versuchen Sie es dann erneut über MCP

Timeout

Fehler: PCILeech command timed out Lösung: Erhöhen Sie pcileech.timeout_seconds in config.json

Projektstruktur

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

Einschränkungen

Nur Windows (PCILeech ist in diesem Repository auf Windows fokussiert)
Erfordert kompatible PCILeech-Hardware für echte Speicheroperationen
Lesegrößenbeschränkungen:
- memory_read: bis zu 1 MB
- memory_format: bis zu 4 KB (lesbare Ausgabe)
Einige Tools sind nur für FPGA (probe/TLP/config)
PCILeech-Befehle werden sequenziell ausgeführt (pro Subprozess-Aufruf)

Sicherheit & Rechtliches

Dieses Tool ist für autorisiertes Debugging, Sicherheitsforschung und Bildungszwecke gedacht. Verwenden Sie es nicht für unbefugten Zugriff oder böswillige Aktivitäten. Sie sind für die Einhaltung der geltenden Gesetze und Vorschriften verantwortlich.

Lizenz

Dieses Projekt umschließt PCILeech, das eine eigene Lizenz hat. Siehe pcileech/LICENSE.txt.

Credits

PCILeech: Ulf Frisk
Model Context Protocol: Anthropic
Autoren: EVAN & MOER

Version

Das Toolset in diesem Repository enthält derzeit das erweiterte Set mit 19 Tools. Für die Paket-/Konfigurationsversion siehe:

pyproject.toml ([project].version)
config.json (server.version)

Support

Discord: Tritt unserem Discord bei
Issues: Öffnen Sie ein Issue in diesem Repository
PCILeech-Dokumentation: PCILeech GitHub
MCP-Dokumentation: MCP-Dokumentation

Changelog

v1.0.0 (16.12.2025)

Erweitert auf 19 MCP-Tools, die den vollen PCILeech-Funktionsumfang abdecken
Virtuellen Adressmodus (pid / process_name) zu Speicher-Tools hinzugefügt
Adressübersetzung, KMD und FPGA/erweiterte Tools hinzugefügt
Umfassendere Validierung und Fehlerbehandlung; nicht-blockierende Serverausführung

v0.1.0 (10.12.2025)

Erstveröffentlichung
Drei MCP-Tools: memory_read, memory_write, memory_format

PCILeech MCP Server