Servidor MCP para PCILeech

Inglés | 中文

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

Related MCP server: Volatility MCP

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

1. 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

2. 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