LeechCore MCP

Read-only physical-memory access over MCP. The native backend calls LeechCore's LcCreate, LcRead, and LcClose directly. A raw-file backend supports offline inspection without a native runtime.

The server exposes nine tools over stdio. Targets, address ranges, and read limits are set in a local JSON file; MCP clients cannot change them. There is no process lookup, virtual-address translation, memory-write API, or HTTP listener.

Requirements

• Windows x64 and 64-bit Python 3.10 or later, including pythonw.exe.

• PowerShell 5.1 or later for the setup script.

• For native access: a trusted x64 leechcore.dll and its matching device dependencies. DLLs, drivers, and firmware are not included.

Related MCP server: memscope-mcp

Install

Clone the repository and run setup:

git clone https://github.com/0xTracepacket/leechcore-mcp.git
cd leechcore-mcp
.\scripts\setup.ps1

To select a Python installation:

.\scripts\setup.ps1 -Python 'C:\Python311\python.exe'

Setup creates .venv, installs hash-locked dependencies, generates a 64 KiB synthetic demo, and prints MCP client configuration. It preserves an existing demo configuration and does not edit client settings or open a device.

Connect a client

Copy the TOML or JSON snippet printed by setup into your MCP client's settings. To generate it again:

.\.venv\Scripts\python.exe -m leechcore_mcp client-config --config .\demo\config.json --format codex
.\.venv\Scripts\python.exe -m leechcore_mcp client-config --config .\demo\config.json --format json

Restart the client connection, then call these tools in order:

The server waits for MCP messages on stdin when started manually. Use doctor for command-line diagnostics, not serve.

Native access

Copy examples/leechcore.example.json to a private configuration file. Set dll_path, select device: "fpga" or a local dump-file path, and replace allowed_ranges with the physical ranges you are authorized to inspect. Relative paths resolve from the configuration directory.

Native reads acquire complete 4096-byte pages and return the requested slice. The entire enclosing page range must be allowed: one byte at 0x1001 requires 0x1000 through 0x1fff. Budgets count requested bytes, not native bus traffic.

.\.venv\Scripts\python.exe -m leechcore_mcp --config .\target.json doctor
.\.venv\Scripts\python.exe -m leechcore_mcp client-config --config .\target.json --format codex

doctor checks files, configuration, and DLL architecture without loading the DLL. memory_open loads it in the acquisition worker. Use a trusted runtime: the read-only tool API does not restrict code inside an external DLL or driver.

See setup for configuration fields, client integration, and the optional native check.

Tools

All addresses are 0x-prefixed strings. File addresses are byte offsets; native addresses are physical addresses.

The leechcore://policy resource exposes the configured ranges and limits without opening the source. Architecture covers types, bounds, timeouts, and output semantics; demo calls provide sample arguments.

Test and build

.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe -m pip check
.\.venv\Scripts\python.exe .\scripts\build_bundle.py

The builder writes a source ZIP and SHA-256 checksum to dist, with a per-file manifest inside the archive. Runtime binaries, memory files, logs, private configurations, and virtual environments are excluded.

For development, install .[dev], then run ruff check . and ruff format --check .. CI runs lint, formatting, and tests on Windows with Python 3.10 and 3.14.

Release verification passed 97 tests on Python 3.10.5 and 3.14.0, plus LeechCore 2.23.3 native reads and an MCP workflow against synthetic data. FPGA and live-target access have not been tested. See the verification record.

Data handling

The MCP client can forward returned memory to its provider and retain it in transcripts. Check that data path before connecting real memory. Treat returned bytes and decoded strings as data, not instructions. Optional JSONL audit logs contain operation metadata, not raw memory.

Reference

• Setup · Architecture · Troubleshooting

• Runtime provenance · Third-party notices · Changelog

• LeechCore C API