CE MCP Backend

Structured Cheat Engine 7.7 dynamic analysis through MCP for explicitly authorized Windows processes. The backend excludes arbitrary Lua, shell commands, injection, and memory writes.

The standalone Windows release requires neither Python nor a Codex plugin or skill. See CE_MCP_TOOLS.md for the tool catalog and ARCHITECTURE.md for trust boundaries.

Install

Requirements: 64-bit Windows and Cheat Engine 7.7. Extract ce-mcp-windows-x64.zip, close all CE instances, and run:

powershell.exe -NoProfile -ExecutionPolicy Bypass `
  -File .\install.ps1 `
  -CheatEngineDir "C:\tools\Cheat Engine"

The installer creates:

Cheat Engine/
|-- autorun/
|   `-- ce_mcp_bridge.lua
`-- mcp/
    |-- server.exe
    |-- ce-mcp-control.exe       optional
    |-- config.json
    |-- http.token
    `-- standalone runtime files

The first install creates a random 48-byte token restricted to the installing Windows user. Upgrades preserve config.json and http.token; use -RotateToken only when all clients can be updated. Restart CE after install. CE autorun owns server.exe startup and shutdown.

Related MCP server: Binary MCP Server

Connect a client

The default endpoint is http://127.0.0.1:8001/mcp. For Codex, expose the installed token through a user environment variable and register the endpoint:

$tokenPath = "C:\tools\Cheat Engine\mcp\http.token"
$token = [IO.File]::ReadAllText($tokenPath).Trim()
[Environment]::SetEnvironmentVariable("CE_MCP_TOKEN", $token, "User")

codex mcp add cheat-engine `
  --url http://127.0.0.1:8001/mcp `
  --bearer-token-env-var CE_MCP_TOKEN

Restart Codex after changing its environment. Other Streamable HTTP clients use the same endpoint and Authorization: Bearer <token>.

The server reads authentication from CE_MCP_TOKEN when present, otherwise from tokenFile in config.json. It refuses HTTP startup without either.

Configuration and health

Default mcp\config.json:

{
  "transport": "streamable-http",
  "host": "127.0.0.1",
  "port": 8001,
  "tokenFile": "http.token",
  "requestDeadlineMs": 5000,
  "maxOutputBytes": 1048576,
  "exitWhenCeExits": true
}

Only 127.0.0.1, ::1, and localhost are accepted. Do not proxy or expose this plaintext endpoint. maxOutputBytes accepts 4096 through 4194304 bytes; oversized results return OUTPUT_LIMIT_EXCEEDED with measured and configured sizes instead of truncated JSON.

Invoke-RestMethod http://127.0.0.1:8001/health/live
$headers = @{ Authorization = "Bearer $env:CE_MCP_TOKEN" }
Invoke-RestMethod http://127.0.0.1:8001/health/ready -Headers $headers

Liveness proves only that HTTP is serving. Authenticated readiness also checks the CE bridge through ce.status.

Use

Begin with ce.status, select and attach an explicit PID through ce.process, and preserve returned session, generation, and debugger stop-generation values. Close owned operations and breakpoints. Never automatically retry an OUTCOME_UNKNOWN mutation.

Tool results contain one complete JSON object in the MCP text content block; the server does not advertise or return structuredContent. suggestedAction and nextActions are optional backend-authored hints, not CE or MCP directives, and are never executed by the server.

DBK and DBVM remain disabled and are never initialized by this project. Each simultaneous CE instance requires a distinct configured HTTP port.

Optional host controller

Normal manual CE startup and shutdown remains supported. The optional controller provides terminal lifecycle operations:

& "C:\tools\Cheat Engine\mcp\ce-mcp-control.exe" status
& "C:\tools\Cheat Engine\mcp\ce-mcp-control.exe" start
& "C:\tools\Cheat Engine\mcp\ce-mcp-control.exe" stop
& "C:\tools\Cheat Engine\mcp\ce-mcp-control.exe" restart

It returns one bounded JSON object. It starts CE, never server.exe; normal stop and restart refuse attached or unobservable state. See the host-control contract for arguments, exit codes, and force semantics.

Development

Local testing with OpenCode

Requires Python 3.10 or newer and uv. Close CE, then run from the repository root, replacing the CE path with your installation directory:

uv run --locked ce-mcp-install-bridge --ce-dir "C:\tools\Cheat Engine"

This installs only autorun\ce_mcp_bridge.lua. Add --replace to explicitly overwrite an existing bridge. Start CE afterward and keep it running.

Merge this local MCP entry into your project's opencode.json or global ~/.config/opencode/opencode.json, replacing the repository path with your absolute checkout path. If you already have a ce-mcp remote entry, replace that entry with the local configuration below (remove its url). Preserve other entries under mcp, such as idalib:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ce-mcp": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "C:\\path\\to\\CE-mcp-backend",
        "run",
        "--locked",
        "ce-mcp-backend",
        "--transport",
        "stdio"
      ],
      "enabled": true,
      "timeout": 120000
    }
  }
}

OpenCode launches the stdio server; do not launch a separate stdio process manually. This setup needs neither an HTTP token nor mcp\config.json. The startup timeout allows time for uv to prepare the environment on first run. Restart OpenCode after updating its configuration and check opencode mcp list.

For a bridge-only source test, avoid the release's automatic HTTP startup: if both mcp\server.exe and mcp\config.json exist in the CE directory, the Lua bridge launches that server when CE starts. With CE closed, temporarily rename mcp\config.json before testing stdio, then restore it when returning to the release setup.

Build and verification

Python 3.10 or newer and uv are required:

uv sync --locked --group build
uv run --locked python -m unittest discover -s tests -v
powershell.exe -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\build-standalone.ps1
uv run --locked python .\scripts\verify-release.py `
  .\dist\ce-mcp-windows-x64
uv run --locked python .\scripts\verify-compiled.py `
  --server .\dist\ce-mcp-windows-x64\mcp\server.exe `
  --controller .\dist\ce-mcp-windows-x64\mcp\ce-mcp-control.exe

Hosted CI runs source and compiled scripted tests without CE. Controlled real-CE smoke tests are a local release gate. CE-facing changes must follow DEVELOPMENT_WORKFLOW.md.