memscope-mcp

Scriptable Windows process-memory research through MCP.

memscope-mcp is a Windows x64 Model Context Protocol (MCP) server for process-memory research and reverse engineering. It combines a small direct MCP surface with in-process Lua composition through Lupa, so multi-step work can execute near the target instead of becoming a sequence of client round trips.

Core workflows include Windows process memory inspection, typed reads and writes, AOB scanning, pointer chains, Lua scripting, inline hooking, and pre-attach PEB inspection. Optional plugins add specialized Lua functions without adding MCP tools.

Windows x64 host and x64 targets · 64-bit Python 3.10+ · CI: Python 3.10–3.14 · MCP over stdio · MIT

Quickstart

Requirements: Windows x64, 64-bit Python 3.10 or newer, and an MCP-compatible client.

python -m pip install memscope-mcp

Configure an MCP client to start the installed stdio server:

{
  "mcpServers": {
    "memscope": {
      "command": "memscope-mcp"
    }
  }
}

Read the Notepad MZ signature

Open Notepad and locate its process:

processes(filter="notepad", limit=10)

Attach to that exact instance and inspect its modules:

attach(process_name="notepad.exe", pid=<selected_pid>)
modules(filter="notepad", limit=10)

Resolve the executable base and read its DOS signature in one Lua call:

lua(script="""
local base = getModuleBase("notepad.exe")
if not base then
    error("notepad.exe module not found")
end

addResult("module_base", toHex(base))
addResult("dos_signature", readBytesHex(base, 2))
""")

A normal PE image returns dos_signature as "4D 5A". This workflow performs process discovery, exact-PID attachment, module resolution, and memory reads without modifying the target.

Capabilities and MCP tools

The current source exposes exactly 11 MCP tools. Detailed parameter contracts belong in the linked reference documentation rather than this overview.

Area	MCP tools	Capabilities
Processes and session	processes, attach, modules	Filter running processes, inspect process and service details, attach to a selected PID, and inspect or refresh the module snapshot.
Memory	read, write, dump, chain	Read and write typed scalar, string, byte, pointer, and common structured values; inspect unknown regions; follow pointer chains with trace output. Addresses may use hexadecimal or module-plus-offset forms.
Scanning	scan, scan_many	Strict AOB scanning over structured scopes. scan supports addresses, first, and count, including resumable address pages; scan_many supports keyed first and count queries in one shared traversal. Both return explicit status.
Automation and scripts	lua, scripts	Run composed Lua work in-process through Lupa, or list and run saved Lua scripts with arguments.

Scanning supports all-module, selected-module, and bounded range scopes with memory-type and executable/writable filters. Module-based scopes may also use case-insensitive PE-section filters. Address results are paged; batch scans evaluate keyed patterns in a shared traversal. See the scanning contract for request forms, continuation, validation, and status semantics.

How MCP tools, Lua, and plugins fit together

MCP client
    |
    | stdio
    v
11-tool MCP surface --------------------+
    |                                   |
    | direct operation tools            | `lua`
    v                                   v
process session                    Lupa runtime
                                        |
                         core Lua functions + optional plugins
                                        |
                                        v
                              Windows user-mode x64 target

Direct tools cover common discovery, session, memory, scanning, and script operations. The Lua layer exposes finer-grained building blocks for work that benefits from loops, branches, dependent reads, or server-side result shaping.

Core Lua capabilities include typed and bulk memory access, module and PE export resolution, AOB and pointer-reference scans, declarative structure reads, process, thread, service and memory-region inspection, allocations, supported x64 native calls, inline hooks, shared ring-buffer capture, and 64-bit-safe utilities. Native calls and hooks are intentionally summarized here; their detailed contracts are in the Lua reference and hooking documentation. Installed plugins may add further Lua functions.

PEB inspection can identify process details, environment data, debugger state, and remote modules before attachment. See PEB process introspection.

Saved scripts can preserve finder logic rather than fixed addresses, making them reusable across restarts and ASLR changes.

Optional plugins and local data

Two bundled reference plugins are available but remain opt-in:

• il2cpp — Unity IL2CPP runtime and object-layout helpers.
• netcap — Winsock capture and analysis built on the core hooking layer.

Install either plugin explicitly, then restart the MCP server:

memscope-mcp install-plugin il2cpp
memscope-mcp install-plugin netcap

Logs, saved scripts, and installed plugins live under MEMSCOPE_HOME, which defaults to ~/.memscope-mcp. Set the environment variable before startup to relocate the data root. Inspect the resolved directories with:

memscope-mcp paths

Documentation

• Architecture and internals — subsystem design, repository layout, extension model, and session lifecycle.
• Scanning — MCP and Lua scanning contracts, scopes, modes, continuation, and status.
• Lua reference — core Lua functions; installed plugins may add functions.
• Inline hooking — supported hooks, capture behavior, and lifecycle.
• PEB process introspection — pre-attach process and module inspection.

Project links

See CONTRIBUTING.md for development and test guidance, and SECURITY.md for vulnerability reporting. Published changes are listed in GitHub Releases. memscope-mcp is distributed under the MIT License.