GEMPACK MCP

An MCP server that exposes the local GEMPACK CGE toolchain (TABLO, GEMSIM, HAR utilities) as tools Claude can call: compile models, run simulations, read solution and HAR data files, and export to CSV/Excel.

中文速览：这是一个把本机 GEMPACK（TABLO/GEMSIM/HAR 工具链）封装成 MCP 工具的服务， 让 Claude 能直接帮你编译模型、跑模拟、读 SL4/HAR 结果、导出 CSV/Excel。 已注册到 Claude Code（user 作用域），工作区指向存放模型的文件夹（如 ./workspace），开箱即用。

Setup

Licence limitation that shaped the design: this licence does not permit TABLO to generate Fortran code. Only the interpretive GEMSIM engine is available — so compile always targets GEMSIM aux files and run_simulation uses the gemsim (or sagem) solver. TABLO-generated model EXEs are not built.

Tools

All file arguments are workspace-relative (or absolute inside the workspace) and confined to the sandbox root.

Typical flow

1. gempack_list_workspace("examples/minimal") — see the files.

2. gempack_compile_tab("examples/minimal/minimal.tab") — build aux files.

3. gempack_run_simulation("examples/minimal/MINIMAL.CMF") — solve.

4. gempack_read_solution(<the .sl4 from step 3>) — list result variables.

5. gempack_read_har_header(<solution_har>, <header code>) — read values.

Note: some tools leave artifacts next to your model files by design — seehar writes <stem>-har.see, read_solution writes <stem>_sol.har, read_har_header writes _<stem>_<header>.csv. These are returned as paths so you can open them; delete them if you don't want them.

Install / register

To install and register:

# 1. dependencies
.venv\Scripts\python.exe -m pip install -r requirements.txt

# 2. register with Claude Code (user scope, stdio)
claude mcp add -s user gempack -e GEMPACK_WORKSPACE=./workspace -- `
  "<path-to-repo>\.venv\Scripts\python.exe" `
  "<path-to-repo>\server.py"

# 3. verify
claude mcp list        # -> gempack: ... ✓ Connected

To remove: claude mcp remove gempack -s user.

Use a forward slash (e.g. D:/models) for the workspace value — a trailing backslash gets escaped against the quote on Windows and breaks claude mcp add.

Changing the sandbox root

The server reads file paths only inside its allowed roots. Set:

• GEMPACK_WORKSPACE — primary root (relative paths resolve here).

• GEMPACK_EXTRA_ROOTS — extra read/write roots, ;-separated (e.g. add F:\).

Anything outside these roots is refused (verified: C:\Windows\win.ini is blocked).

Configuration (env vars)

See .env.example. Key defaults:

A .env file in the project root is loaded automatically; the MCP client's env block and real environment variables override it.

HTTP transport (optional — for Claude on another machine)

Not needed for local use. If you want a remote Claude to reach this server:

$env:GEMPACK_TOKEN = "<a-long-random-secret>"   # required
.\run-http.bat          # serves http://127.0.0.1:8765/mcp

Clients must send Authorization: Bearer <token>. To accept connections from other machines, set GEMPACK_HTTP_HOST=0.0.0.0 and open the port in the firewall (see run-http.bat for the netsh command).

Tests

tests\test_e2e.py drives every operation against a pristine copy of the minimal example (in tests\minimal\) using the real GEMPACK engine:

$env:PYTHONPATH = (Get-Location)
.venv\Scripts\python.exe tests\test_e2e.py
# -> === required: 9/9 passed; info: 2/2 ok ===

Layout

gempack-mcp\
  server.py            FastMCP server: 7 tools + stdio/HTTP launch
  gempack_mcp\
    config.py          env-var config (paths, roots, timeouts, token)
    sandbox.py         path confinement to the allowed roots
    runner.py          non-interactive subprocess runner (EOF stdin, file snapshot)
    gp.py              the GEMPACK operations (verified CLI invocations)
  tests\test_e2e.py    end-to-end test against the minimal example
  run-stdio.bat        launch stdio manually
  run-http.bat         launch HTTP (needs GEMPACK_TOKEN)
  .env.example         documented configuration
  requirements.txt