Esquie

MCP server providing computation, encoding, and note-taking tools for AI-assisted reverse engineering. Designed to complement disassembler-specific MCP servers (IDA Pro, Ghidra, Binary Ninja) by handling the ad-hoc computation side of RE work: struct unpacking, address math, crypto checks, encoding/decoding, and arbitrary Python scripting.

Renamed from re-helper-tools in 0.3.0. Existing users should remove the old image/container: docker rmi re-helper-sandbox:latest && docker rm -f re-helper-sandbox.

Prerequisites

• Node.js 20 or later

• npm (included with Node.js)

• Docker Desktop or Docker Engine — must be running before using python_eval

Verify your environment:

node --version   # v20.x or later
docker info      # should print server info without errors

Related MCP server: cutterMCP

Quick Start

# Clone and enter the project
git clone <repo-url> && cd esquie

# Install dependencies and compile TypeScript
npm install
npm run build

# Build the Python sandbox Docker image (~1-2 min on first run)
docker build -t esquie-sandbox:latest .

The Docker image is also built automatically on the first python_eval call if it doesn't exist, but pre-building avoids a delay during your first session.

MCP Configuration

Claude Code

Add to your project's .mcp.json or ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "esquie": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/esquie"
    }
  }
}

cwd must point to the project root so the server can locate the Dockerfile for auto-building the sandbox image.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "esquie": {
      "command": "node",
      "args": ["/absolute/path/to/esquie/dist/index.js"],
      "cwd": "/absolute/path/to/esquie"
    }
  }
}

Tools Reference

python_eval

Execute arbitrary Python in a sandboxed Docker container. Session state (variables, imports, function definitions) persists across calls within the same server session.

Pre-installed packages: capstone, lief, pycryptodome, dill. To add packages, build a custom image extending esquie-sandbox:latest and point the server at it via ESQUIE_SANDBOX_IMAGE (see Extending the sandbox). Network is disabled inside the container by design, so pip install from python_eval is not possible.

Examples:

# Expression — result is returned automatically
0x401000 + 0x1a4
# → 4198564

# State persists across calls
from capstone import *
md = Cs(CS_ARCH_X86, CS_MODE_64)

# Subsequent call can use `md`
for insn in md.disasm(b"\x55\x48\x89\xe5", 0x1000):
    print(f"0x{insn.address:x}: {insn.mnemonic} {insn.op_str}")
# → 0x1000: push rbp
# → 0x1001: mov rbp, rsp

Hex/Binary Utilities

Native TypeScript tools — no Docker overhead, instant response.

All hex parameters accept optional 0x prefix and ignore whitespace.

Sandbox Management

Scratchpad

Key-value store for persisting analysis notes, renamed symbols, struct definitions, and other context. By default in-memory only (cleared on server restart). Set ESQUIE_NOTES_FILE to an absolute file path to persist notes to disk.

Notes are also exposed as MCP resources under note://{key} URIs, so MCP clients that support resources can browse and reference them directly.

Sandbox Security Model

The python_eval container runs with multiple layers of isolation:

Architecture

Claude Code / Claude Desktop
        │
        │ stdio (JSON-RPC)
        ▼
┌─────────────────────────┐
│  MCP Server (Node.js)   │
│                         │
│  ┌───────────────────┐  │
│  │ hex-utils.ts      │──┼── hex_to_dec, xor_buffers, hash, ...
│  │ (native TS)       │  │
│  └───────────────────┘  │
│  ┌───────────────────┐  │
│  │ scratchpad.ts     │──┼── set_note, get_note, list_notes, ...
│  │ (Map + opt. JSON) │──┼── MCP resources: note://{key}
│  └───────────────────┘  │
│  ┌───────────────────┐  │
│  │ python-eval.ts    │──┼── python_eval, reset_sandbox,
│  │ (5 MCP tools)     │  │   upload/list/download_from_sandbox
│  └─────────┬─────────┘  │
│            │ calls      │
│            ▼            │
│  ┌─────────┴─────────┐  │       ┌───────────────────────────────┐
│  │ sandbox.ts        │──┼──────►│  Docker Container             │
│  │ (Docker lifecycle)│  │       │  (esquie-sandbox:latest)      │
│  └───────────────────┘  │       │                               │
│                         │       │  python3 /opt/runner.py       │
│                         │       │  ├─ loads session from pkl    │
│                         │       │  ├─ exec(code) in namespace   │
│                         │       │  └─ saves session to pkl      │
└─────────────────────────┘       └───────────────────────────────┘

• Lazy init: Container is created on the first python_eval call and kept alive for the session.

• Session persistence: Python variables survive across calls via dill serialization to /tmp/session.pkl inside the container.

• Auto-expiry: Container is automatically destroyed after 30 minutes of idle time (configurable via ESQUIE_SANDBOX_IDLE_TIMEOUT).

• Cleanup: Container is stopped and removed on server shutdown (SIGINT/SIGTERM).

Configuration

Resource limits and timeouts are configured via environment variables:

Out-of-range values are clamped to the nearest bound and a warning is logged to stderr.

Set them in your MCP config's env block or export before starting the server:

{
  "mcpServers": {
    "esquie": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/esquie",
      "env": {
        "ESQUIE_SANDBOX_MEMORY": "1024",
        "ESQUIE_SANDBOX_TIMEOUT": "60000",
        "ESQUIE_NOTES_FILE": "/Users/me/.esquie/notes.json",
        "ESQUIE_SANDBOX_MOUNT": "/Users/me/samples"
      }
    }
  }
}

Extending the sandbox

The default sandbox image is intentionally minimal: capstone, lief, pycryptodome, dill. The container has no network access by design, so packages cannot be installed at runtime via python_eval. To add tools (e.g. pwntools, unicorn, keystone-engine, yara-python, angr, custom wheels), bake them into a derived image and point Esquie at it.

1. Build the base image once:

   docker build -t esquie-sandbox:latest .

2. Write a custom Dockerfile that extends it:

   FROM esquie-sandbox:latest
   USER root
   RUN apt-get update && apt-get install -y --no-install-recommends \
           build-essential cmake pkg-config libffi-dev \
       && pip install --no-cache-dir --target=/opt/pylibs \
           pwntools unicorn keystone-engine yara-python \
       && apt-get purge -y build-essential cmake pkg-config \
       && apt-get autoremove -y \
       && rm -rf /var/lib/apt/lists/*
   USER sandbox

3. Build it:

   docker build -t my-esquie-sandbox:latest -f Dockerfile.custom .

4. Set ESQUIE_SANDBOX_IMAGE in your MCP config:

   "env": { "ESQUIE_SANDBOX_IMAGE": "my-esquie-sandbox:latest" }

5. If a previous container exists, force a fresh one so the new image takes effect:

   docker rm -f esquie-sandbox

When ESQUIE_SANDBOX_IMAGE is set to a tag other than the default, the server will not auto-build the image — it expects you to have built or pulled it. Missing custom image → first python_eval fails with an actionable error pointing at the build command.

Development

# Run in development mode (auto-compiles via tsx)
npm run dev

# Compile TypeScript to dist/
npm run build

# Rebuild the Docker image (required after changing runner.py or Dockerfile)
docker build -t esquie-sandbox:latest .

# Force-recreate the sandbox container (e.g. after image rebuild)
docker rm -f esquie-sandbox

CI runs npm ci && npm run build on every push and PR to main (.github/workflows/build.yml).

Project Structure

esquie/
├── package.json
├── tsconfig.json
├── Dockerfile                 # Python sandbox image definition
├── .github/workflows/
│   └── build.yml              # CI build check
├── src/
│   ├── index.ts               # Entry point: server setup, tool/resource registration, shutdown
│   ├── docker/
│   │   ├── config.ts          # Env var config parsing
│   │   ├── sandbox.ts         # DockerSandbox class: container lifecycle + exec + file I/O
│   │   └── runner.py          # Python runner baked into Docker image
│   └── tools/
│       ├── python-eval.ts     # python_eval, reset_sandbox, upload/list/download
│       ├── hex-utils.ts       # Native hex/binary/encoding tools
│       └── scratchpad.ts      # Key-value notepad (in-memory + optional JSON persistence)
└── dist/                      # Compiled output (git-ignored)

Troubleshooting

python_eval fails with "Cannot connect to the Docker daemon" Docker Desktop or Docker Engine is not running. Start it and try again.

python_eval hangs on first call The sandbox Docker image is being built automatically. This takes 1-2 minutes on first run. Pre-build with docker build -t esquie-sandbox:latest . to avoid this.

"Conflict. The container name /esquie-sandbox is already in use" A leftover container from a previous session. Remove it:

docker rm -f esquie-sandbox

Session state is lost The container was destroyed (server restart, Docker restart, manual removal). State lives in /tmp inside the container and does not survive container removal. This is by design.

"Execution timed out" The default timeout is 30 seconds. Pass a higher timeout value (in ms) for long-running computations. Maximum practical limit depends on the MCP client.

Docker image is stale after editing runner.py Rebuild the image and remove the old container:

docker build -t esquie-sandbox:latest .
docker rm -f esquie-sandbox

Upgrading from re-helper-tools Remove the old image and container after upgrading:

docker rmi re-helper-sandbox:latest
docker rm -f re-helper-sandbox

Update any RE_SANDBOX_* env vars in your MCP config to ESQUIE_SANDBOX_*.