PCILeech MCP 服务器

English | 中文

English

一个模型上下文协议 (MCP) 服务器，为 PCILeech 提供标准化的接口，用于执行基于 DMA 的内存操作。这使得 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 + 字节/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?) → 十六进制数据 + 元数据
memory_write(address, data, pid?, process_name?) → 成功/确认
memory_format(address, length, formats?, pid?, process_name?) → hexdump/ASCII/数组/原始数据

系统

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）

架构

双层设计

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
模型上下文协议: Anthropic
作者: EVAN & MOER

版本

本仓库中的工具集目前包含 19 个工具的扩展集。有关包/配置版本，请参考：

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

支持

Discord: 加入我们的 Discord
问题：在本仓库中提交 issue
PCILeech 文档: PCILeech GitHub
MCP 文档: MCP 文档

更新日志

v1.0.0 (2025-12-16)

扩展至 19 个 MCP 工具，涵盖完整的 PCILeech 功能
为内存工具添加了虚拟地址模式 (pid / process_name)
添加了地址转换、KMD 和 FPGA/高级工具
增强了验证和错误处理；非阻塞服务器执行

v0.1.0 (2025-12-10)

初始版本
三个 MCP 工具：memory_read, memory_write, memory_format

PCILeech MCP Server