Servidor MCP para PCILeech

Inglés

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona una interfaz estandarizada para PCILeech para operaciones de memoria basadas en DMA. Esto permite a los clientes MCP (por ejemplo, Claude Code) realizar flujos de trabajo de memoria/depuración a través de llamadas a herramientas.

Autores: EVAN & MOER Soporte: Únete a nuestro Discord

Características

19 herramientas MCP agrupadas por capacidad:
- Memoria central: memory_read, memory_write, memory_format
- Sistema: system_info, memory_probe, memory_dump, memory_search, memory_patch, process_list
- Traducción de direcciones: translate_phys2virt, translate_virt2phys, process_virt2phys
- Módulo de kernel (KMD): kmd_load, kmd_exit, kmd_execute, kmd_list_scripts
- Avanzado/FPGA: benchmark, tlp_send, fpga_config
Modo de dirección virtual: las herramientas de memoria admiten pid o process_name (mutuamente excluyentes)
Servidor no bloqueante: las llamadas a PCILeech se ejecutan mediante asyncio.to_thread
Ayudantes de salida: hexdump + ASCII + vistas de byte/DWORD para análisis

Requisitos previos

Windows 10/11 (x64)
Python 3.10+
Hardware PCILeech configurado y funcionando correctamente
Binarios de PCILeech (incluidos en pcileech/)

Inicio rápido

1. Clonar

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. Instalar dependencias

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

Si tienes problemas con la importación/versión de MCP, instala desde pyproject.toml en su lugar:

pip install -e .

3. Verificar PCILeech

cd pcileech
pcileech.exe probe

4. Configurar Claude Code (MCP)

Añade una entrada de servidor (ajusta las rutas):

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

Reinicia Claude Code después de editar la configuración de MCP.

Configuración

config.json controla la ruta del ejecutable de PCILeech y los tiempos de espera:

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

Ejemplos de uso

Una vez configurado, puedes solicitar acciones en lenguaje natural; el cliente las traducirá en llamadas a herramientas:

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

Herramientas MCP (Resumen)

Notas:

Modo de memoria virtual: para herramientas de memoria, usa pid o process_name (no ambos).
Solo FPGA: algunas operaciones requieren un dispositivo basado en FPGA (por ejemplo, memory_probe, tlp_send).

Memoria central

memory_read(address, length, pid?, process_name?) → datos hexadecimales + metadatos
memory_write(address, data, pid?, process_name?) → éxito/confirmación
memory_format(address, length, formats?, pid?, process_name?) → hexdump/ASCII/arrays/raw

Sistema

system_info(verbose?) → sistema objetivo + información del dispositivo
memory_probe(min_address?, max_address?) → regiones legibles (solo FPGA)
memory_dump(min_address, max_address, output_file?, force?) → ruta del archivo de volcado/resultado
memory_search(pattern? | signature?, min_address?, max_address?, find_all?) → coincidencias
memory_patch(signature, min_address?, max_address?, patch_all?) → resultado del parche
process_list() → lista de PID/PPID/nombre

Traducción de direcciones

translate_phys2virt(physical_address, cr3) → detalles de traducción
translate_virt2phys(virtual_address, cr3) → detalles de traducción
process_virt2phys(pid, virtual_address) → detalles de traducción

Módulo de kernel (KMD)

kmd_load(kmd_type, use_pt?, cr3?) → resultado de carga (+ almacena en caché la dirección KMD)
kmd_exit(kmd_address?) → resultado de descarga (usa la dirección almacenada en caché si se omite)
kmd_execute(script_name, kmd_address?, input_file?, output_file?, parameter_string?, parameter_int0?, parameter_int1?)
kmd_list_scripts(platform?) → scripts .ksh disponibles agrupados por plataforma

Avanzado / FPGA

benchmark(test_type?, address?) → resultados en MB/s (depende del hardware)
tlp_send(tlp_data?, wait_seconds?, verbose?) → TLP enviados/recibidos (solo FPGA)
fpga_config(action?, address?, data?, output_file?) → lectura/escritura de configuración (solo FPGA)

Arquitectura

Diseño de dos capas

Capa de servidor MCP (main.py)
- Transporte Stdio, esquemas de herramientas, validación, formato
- Utiliza asyncio.to_thread() para evitar bloquear el bucle de eventos
Envoltorio de PCILeech (pcileech_wrapper.py)
- Llamadas de subproceso a pcileech.exe
- Alineación de direcciones + fragmentación de 256 bytes (comportamiento de display de PCILeech)
- Análisis de salida, tiempos de espera y mapeo de errores

Solución de problemas

PCILeech no encontrado

Error: PCILeech executable not found Solución: verifica config.json → pcileech.executable_path

Hardware no conectado

Advertencia: PCILeech connection verification failed Solución: ejecuta pcileech\pcileech.exe probe y valida los controladores/cableado

El acceso a la memoria falla

Error: Memory read/write failed Solución: valida la dirección/rango en la CLI primero, luego vuelve a intentarlo a través de MCP

Tiempo de espera agotado

Error: PCILeech command timed out Solución: aumenta pcileech.timeout_seconds en config.json

Estructura del proyecto

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

Limitaciones

Solo Windows (PCILeech se centra en Windows en este repositorio)
Requiere hardware PCILeech compatible para operaciones de memoria reales
Límites de tamaño de lectura:
- memory_read: hasta 1 MB
- memory_format: hasta 4 KB (salida legible)
Algunas herramientas son solo FPGA (probe/TLP/config)
Los comandos de PCILeech se ejecutan secuencialmente (por llamada de subproceso)

Seguridad y legalidad

Esta herramienta está destinada a la depuración autorizada, la investigación de seguridad y la educación. No la utilices para acceso no autorizado o actividades maliciosas. Eres responsable de cumplir con las leyes y regulaciones aplicables.

Licencia

Este proyecto envuelve a PCILeech, que tiene su propia licencia. Consulta pcileech/LICENSE.txt.

Créditos

PCILeech: Ulf Frisk
Protocolo de Contexto de Modelo: Anthropic
Autores: EVAN & MOER

Versión

El conjunto de herramientas en este repositorio incluye actualmente el conjunto extendido de 19 herramientas. Para la versión del paquete/configuración, consulta:

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

Soporte

Discord: Únete a nuestro Discord
Problemas: abre un problema en este repositorio
Documentación de PCILeech: GitHub de PCILeech
Documentación de MCP: Documentación de MCP

Registro de cambios

v1.0.0 (2025-12-16)

Ampliado a 19 herramientas MCP que cubren la funcionalidad completa de PCILeech
Se añadió el modo de dirección virtual (pid / process_name) a las herramientas de memoria
Se añadieron herramientas de traducción de direcciones, KMD y FPGA/avanzadas
Se añadió una validación y manejo de errores más amplios; ejecución de servidor no bloqueante

v0.1.0 (2025-12-10)

Lanzamiento inicial
Tres herramientas MCP: memory_read, memory_write, memory_format

PCILeech MCP Server