itasca-mcp

What it does

itasca-mcp is a local Python server that ties an MCP client to ITASCA's geomechanics programs: PFC, FLAC/FLAC3D, 3DEC, MPoint and MassFlow. It has two halves.

The documentation half is now two tools. `itasca_browse_doc` walks one of four bundled trees by path (commands, the Python API, FISH intrinsics, or reference pages such as contact models and plot items), and `itasca_query_doc` searches them by keywords, all four at once unless you pick a tree. You choose the engine with the required `software` parameter. The version defaults to 9.0, and older PFC, FLAC and 3DEC docs are there as 6.0 or 7.0. None of this needs a running engine.

The other five tools drive a live engine. They talk over HTTP to a companion package, itasca-mcp-bridge, which you start inside the engine's IPython console (run the repository's addon.py once, then `import itasca_mcp_bridge; itasca_mcp_bridge.start()` in later sessions). With it the assistant can run Python in the engine's interpreter like a console, submit a script file as a background task, poll its output, interrupt it and page through the task history. That history is kept in the engine's working directory, so it survives a GUI restart. Responses can also tell the assistant what you did in the GUI since the last call, such as console input and the plots or data files you opened.

One thing the README leaves out: in the code, `itasca_execute_code` waits 10 seconds by default and accepts at most 20, a cap set to stay under client request timeouts (utils.py). Anything longer has to go through `itasca_execute_task`. The project comes from an independent developer and is not published by ITASCA.

What it needs

For the execution tools, install itasca-mcp-bridge into the engine's embedded Python, either by running the repository's addon.py in the engine GUI or with `pip install itasca-mcp-bridge` using the engine's own python.exe. Start it again in each new engine session. The setup guide is written for Windows, where the engines install.

Limits

• Limit The five execution tools return a bridge error until itasca-mcp-bridge is running in the engine on port 9001 (or the address you set)
• Platform FLAC 6.x ships Python 2.7, which cannot run the bridge
• Size cap itasca_execute_code times out after 10 s by default and 20 s at most, and cannot be interrupted while it runs
• Size cap itasca_query_doc returns 10 hits by default and up to 20 with limit
• Limit FISH definition blocks must be sent whole in one itasca.command() call, or the engine waits in interactive FISH mode
• Limit The bridge checks PyPI and upgrades itself every time start() runs

The execution tools do nothing until the bridge is running inside the engine; each new engine session needs it started again. FLAC 6.x ships Python 2.7 and cannot run the bridge. Code sent to `itasca_execute_code` blocks until it finishes or hits its timeout (10 s default, 600 s cap) and cannot be stopped; long runs belong in `itasca_execute_task`. FISH definition blocks must be sent whole in one command, or the engine is left waiting in its console. The bridge checks PyPI and upgrades itself each time `start()` runs.

Who it suits

Suits engineers and researchers who already have an ITASCA licence and want an assistant to look up commands, write and run model scripts, and keep an eye on long runs while they carry on in the GUI. The two documentation tools are useful on their own, even with no engine open. It is of no use without ITASCA software, and it is one developer's project, not an ITASCA product. Since it runs arbitrary Python inside the engine, keep it to machines and models where that is acceptable.