ITASCA MCP Server

Community

Drive ITASCA geotechnical and geomechanics simulations through natural conversation

★ 191 Stars Category · Other Very popular

55FMRS · C

itasca-mcp (ITASCA MCP Server) is an MIT-licensed community project that connects AI agents to ITASCA's PFC, FLAC, 3DEC, MPoint, and MassFlow through the Model Context Protocol. It provides 10 tools: 5 documentation tools that need no bridge (command, Python API, and reference doc browsing across multiple engines and versions) and 5 execution tools that require the bridge (interactive REPL, task submission, progress monitoring, interruption, and history). It suits geotechnical users who already have an ITASCA engine installed and want to look up docs and run and monitor simulations conversationally; it is not for users without an ITASCA engine or those expecting official support. The main risks are that execution tools really run simulation code, that the bridge auto-checks PyPI and self-upgrades, and that the model can still generate non-existent commands.

Reliability

10/20

Security and permissions

9/20

Maintenance

12/20

Documentation

13/20

Setup experience

11/20

Read the FMRS scoring method →

itasca-mcp is a Model Context Protocol server that connects AI agents to ITASCA's geomechanics simulation software — PFC, FLAC, 3DEC, MPoint, and MassFlow. Agents can browse and search the selected engine's command, Python API, and reference documentation, submit long-running simulations, monitor progress, interrupt tasks, and browse task history, and execute code in a live REPL while a simulation runs without stopping it. The documentation tools need no bridge; the execution tools require a bridge started inside the ITASCA engine (via addon.py or itasca_mcp_bridge.start()). The engine is chosen through the required software parameter, and command documentation spans versions through the version parameter (PFC 6.0/7.0/9.0, FLAC 7.0/9.0, 3DEC 7.0/9.0). Distributed as the PyPI package itasca-mcp, run with uvx over stdio, MIT licensed — a community project, not an official ITASCA product.

Tools

itasca_execute_code

Executes code in the ITASCA engine; referenced in the README as the way to verify that the bridge connection is established.

Setup

Prepare: install an ITASCA engine (PFC, FLAC, 3DEC, MPoint, or MassFlow; 9.0+ recommended, with PFC 6.0/7.0, FLAC 7.0, and 3DEC 7.0 also supported), install uv (for uvx), and have an MCP-capable AI agent (e.g. Claude Code, Codex CLI, Gemini CLI).
Register the MCP server: use a single command such as claude mcp add itasca-mcp -- uvx itasca-mcp, or fill in the MCP config file manually with {"mcpServers":{"itasca-mcp":{"command":"uvx","args":["itasca-mcp"]}}}.
Start the bridge: download addon.py, then either paste its contents into the engine GUI's IPython console and run them, or execute the file inside the engine GUI (PFC, FLAC, 3DEC, ...).
Verify: restart your AI agent and ask it to call itasca_execute_code to confirm the connection.
Daily startup: in each new engine session, run import itasca_mcp_bridge and itasca_mcp_bridge.start() in the engine's IPython console to get back online (start() checks PyPI for a newer bridge release and self-upgrades before starting).

claude_desktop_config.json

{"mcpServers":{"itasca-mcp":{"command":"uvx","args":["itasca-mcp"]}}}

Generate and validate client config

Fit and risk

Best for

Geotechnical and geomechanics engineers who already have an ITASCA engine installed and want to drive simulations through an AI agent by natural conversation
Users who frequently need to look up PFC/FLAC/3DEC/MPoint/MassFlow commands and Python API documentation
Researchers who submit and monitor long-running simulations while iterating on code
Technical teams using MCP clients such as Claude Code, Codex CLI, or Gemini CLI

Not for

Users without any ITASCA engine installed — the execution tools depend on a local engine and bridge and cannot run simulations on their own
Users expecting official ITASCA support or certification; this is a community project
Users looking for browser, database, or cloud-storage capabilities rather than geomechanics simulation
Users wanting a fully zero-configuration experience — first-time setup requires registering the MCP server and starting the bridge in the engine

Required permissions

Run uvx locally and download/execute the itasca-mcp package from PyPI
Execute code in the ITASCA engine's IPython console to start the bridge (addon.py or itasca_mcp_bridge.start())
Submit code and simulation tasks to the running ITASCA engine through the bridge and read task state and results
Network access to PyPI at bridge startup to check for and possibly self-upgrade to a newer release
Read and write MCP client configuration files to register the server

Risks and side effects

The execution tools run code and simulations in a real ITASCA engine; wrong commands or parameters can produce incorrect results or consume significant compute time and resources
The bridge automatically checks PyPI and self-upgrades, pulling in updates without per-update user confirmation, which introduces supply-chain risk
Documentation browsing reduces but cannot fully eliminate hallucinated commands produced by the model
Long-running simulations, if not properly monitored or interrupted, can tie up machine resources for a long time
This is a community project rather than an official ITASCA release, so compatibility and maintenance cadence are not guaranteed by the upstream vendor

Troubleshooting

If execution tools fail, first confirm the bridge is running inside the ITASCA engine (addon.py or itasca_mcp_bridge.start()); a new engine session requires restarting the bridge
If the connection misbehaves, confirm uv is installed, restart the AI agent, and have it call itasca_execute_code again to verify
If documentation results look wrong, check that the correct software parameter was passed and whether version is needed to select the engine version
If startup fails or the version is stale, re-import and call start() in the engine's IPython console so the bridge can check for and upgrade to a newer release
More checks are listed in the Troubleshooting section of the bootstrap guide: docs/agentic/itasca-mcp-bootstrap.md#troubleshooting

Use cases

Run a biaxial compression test on a dense specimen and plot the stress–strain curve

Build a slope model in FLAC3D and find the factor of safety

Model a tunnel excavation in jointed rock with 3DEC and check block displacements around the opening

Simulate a landslide runout with MPoint and report the final deposit profile

Check the current unbalanced force while a simulation is still running, without stopping it

Compare how zone commands differ between FLAC 7.0 and 9.0

Use the REPL for quick iteration before writing a full script

Supported clients

Claude CodeFull support

Codex CLIFull support

Gemini CLIFull support

GitHub Copilot CLIPartial support

OpenCodePartial support

Related MCP servers

Compare with other MCP servers