# ITASCA MCP Server [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/yusong652/itasca-mcp  
**GitHub Stars:** 220  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/itasca-mcp-server

## Description
Give AI agents full access to ITASCA PFC, FLAC3D, 3DEC - documentation, simulation, plot capture.

## Tools
Capabilities this server exposes over MCP:

- **itasca_browse_commands** — Browse Itasca command documentation by path (like glob + cat).

Navigation levels:
- No command: All command categories overview
- Category only (e.g., "ball"): List commands in category
- Full command (e.g., "ball create"): Full documentation

When to use:
- You know the command category or exact command
- You want to explore available commands

Related tools:
- itasca_query_command: Search commands by keywords (when path unknown)
- itasca_browse_reference: Browse reference docs (e.g., "contact-models linear")
- **itasca_browse_python_api** — Browse Itasca Python SDK documentation by path (like glob + cat).
- **itasca_browse_reference** — Browse ITASCA reference documentation (syntax elements, model properties).

Works across engines via the required ``software`` selector (pfc/flac/3dec).
References are language elements used within commands, not standalone commands.

Navigation levels:
- No topic: All reference categories for the engine
- Category (e.g., "constitutive-models"): List items in category
- Full path (e.g., "constitutive-models mohr-coulomb"): Full documentation
- Sub-item path (e.g., "plot-items zone contour"): Sub-item details

When to use:
- Need material/contact/joint model property names (kn, ks, fric, cohesion, friction, ...)
- Need range filtering syntax (position, cylinder, group, id)
- Need plot item configuration (contour, label, color-by, cut, transparency, legend)
- Setting up model-assignment commands (e.g. "... cmodel assign ... property ...")
- Using range filters in any command
- Configuring "plot item create" commands

Related tools:
- itasca_browse_commands: Command syntax (e.g., "zone create")
- itasca_query_command: Search commands by keywords
- **itasca_query_command** — Search Itasca command documentation by keywords (like grep).

Returns matching command paths. Use itasca_browse_commands for full documentation.

When to use:
- You have keywords but don't know exact command path
- Example: "ball create", "contact property", "model solve"

Related tools:
- itasca_browse_commands: Get full documentation for a known command path
- itasca_browse_reference: Browse reference docs (e.g., "contact-models linear")
- itasca_query_python_api: Search Python SDK by keywords
- **itasca_query_python_api** — Search Itasca Python SDK documentation by keywords (like grep).

Returns matching API paths with signatures. Use itasca_browse_python_api for full documentation.

When to use:
- You have keywords but don't know exact API path
- Example: "ball velocity", "create", "contact force"

Related tools:
- itasca_browse_python_api: Get full documentation for a known API path
- itasca_query_command: Search Itasca commands by keywords
- **itasca_execute_task** — Submit a Python script file for asynchronous execution in the Itasca engine.

Returns a task_id immediately; the script runs in the background.
Companion tools manage the lifecycle:
- itasca_check_task_status: poll output, progress, and final status
- itasca_interrupt_task: cancel a running task
- itasca_list_tasks: browse task history
For synchronous, inline execution, use itasca_execute_code instead.

While the task is cycling, itasca_execute_code shares the same
__main__ namespace in the engine's main thread, so you can
inspect or modify simulation state live — probe progress, tune
parameters mid-run, swap callbacks, or trigger early termination
via a sentinel variable. Submit with reasonable starting values
and refine as the task runs.

Console output from itasca.command() inside the script (table
dumps, list output, command summaries) is captured into the task
log alongside Python prints, visible through
itasca_check_task_status.

Script-writing rules:
- Multi-line itasca.command("""...""") batches are normalized
  to one engine call per command, keeping the task interruptible
  mid-batch. Normalization recognizes itasca.command through its
  import name; call it through that name directly — rebinding
  via intermediate variables (`_it = itasca`) bypasses it and
  logs a bridge warning.
- Pass each FISH definition block (`fish define` /
  `fish operator` / legacy bare `define`, through its
  terminating standalone `end`) whole, in ONE itasca.command()
  string; feeding one line-by-line leaves the engine blocked in
  interactive FISH mode until completed manually in the GUI
  console. Per-line loops are fine for ordinary commands.
- `program call '<file>'` (.p3dat / .p2dat / .dat / ...) is
  supported: the bridge runs the file inline, one command per
  engine call, so the bridge stays reachable, the task stays
  interruptible, and the file's output lands in the task log
  command by command.
- **itasca_check_task_status** — Check status and paginated output for a submitted Itasca task.

Output combines Python prints and Itasca console output from
itasca.command() calls (table dumps, list output, command
summaries) interleaved in execution order. Use skip_newest /
limit to paginate, or filter to keep only matching lines.
- **itasca_list_tasks** — List tasks tracked by the bridge, newest first.

Read-only. Each entry carries task_id, status (pending / running /
completed / failed / interrupted), description, entry_script,
start_time, end_time and elapsed_time; total_count gives the size
of the full history for paging via skip_newest + limit.

Task history is persisted in the engine working directory and
survives GUI restarts. Use this to recover a task_id from an
earlier session, to see what is running or recently finished, or
as a cheap bridge-connectivity check. For a task's output and
result use itasca_check_task_status; to submit a script use
itasca_execute_task.
- **itasca_interrupt_task** — Request interruption of a pending or running Itasca task.

Returns as soon as the request is accepted; it does not wait for
the task to stop. Confirm the stop and read the output produced
so far with itasca_check_task_status. Only the script stops; the
engine state is preserved, so you can inspect it with
itasca_execute_code or continue from it with a new
itasca_execute_task. Tasks already completed, failed or
interrupted return an error. If the task_id is unknown, find it
with itasca_list_tasks.
- **itasca_execute_code** — Execute Python code synchronously in the running Itasca engine process.

Returns stdout and an optional result variable immediately.
Code runs in the engine's main thread, sharing the same __main__
namespace as any running task — side effects persist and are
immediately visible to the task on its next cycle.

The tool stays responsive while a task submitted via
itasca_execute_task is cycling (calls interleave at cycle
gaps), so use it as a live REPL — nothing has to be
pre-scripted into the task up front. Typical uses:
- Query model state and read Itasca command output:
  itasca.command('ball list') etc. — table dumps, list output,
  and command summaries are captured and interleaved with
  Python prints in execution order
- Live inspection and tuning during a running task: check
  forces or contact statistics, modify parameters, swap
  callbacks, set sentinel variables the task reads each cycle
- Create and export plots: itasca.command('plot ...')

Environment: the engine's embedded Python interpreter
(Itasca 9+ → Python 3.10, pre-9 → Python 3.6 or older; the
product+version is encoded in sys.executable, e.g. PFC900).
When unsure, check sys.version_info before relying on newer
syntax.

Code-writing rules (shared with itasca_execute_task):
- Multi-line itasca.command("""...""") batches are normalized
  to one engine call per command, keeping the bridge reachable
  mid-batch. Normalization recognizes itasca.command through
  its import name; call it through that name directly —
  rebinding via intermediate variables (`_it = itasca`)
  bypasses it and the output carries a bridge warning.
- Pass each FISH definition block (`fish define` /
  `fish operator` / legacy bare `define`, through its
  terminating standalone `end`) whole, in ONE itasca.command()
  string; feeding one line-by-line leaves the engine blocked in
  interactive FISH mode until completed manually in the GUI
  console. Per-line loops are fine for ordinary commands.
- `program call '<file>'` (.p3dat / .p2dat / .dat / ...) is
  supported: the bridge runs the file inline, one command per
  engine call, so the bridge stays reachable, the run stays
  interruptible, and the file's output arrives command by
  command.

Synchronous semantics: the request blocks until the code
finishes or hits the timeout (default 10s, max 20s), and
output is returned in full. The call is not tracked by
itasca_list_tasks and cannot be interrupted mid-execution.
For cancellable, pollable, or background work, submit via
itasca_execute_task instead.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

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

## Documentation

## What ITASCA MCP Server MCP server does

ITASCA MCP Server MCP server exposes ITASCA geomechanics software to MCP-compatible AI agents. Supported engines include PFC, FLAC, 3DEC, MPoint, and MassFlow, with documentation available across the versions listed by the project. The documentation corpus covers engine commands, Python APIs, reference material, and plot items.

The server is intended for workflows where an agent needs both guidance and access to a running simulation environment. For example, an agent can look up commands, build a model, run a biaxial test, inspect intermediate results, or help diagnose a command entered in the engine console.

## How it works

The server provides ten tools divided into two groups. Five documentation tools let an agent browse and search the selected engine’s command tree, Python API, and reference documentation. These tools do not require a bridge. The selected product and version are supplied through tool parameters, allowing the agent to work with the relevant documentation set.

Five execution tools handle an interactive REPL, long-running task submission, progress checks, interruption, and task history. These operations require a bridge started from inside the ITASCA engine. With the bridge active, an agent can run code while a simulation continues, check model state without stopping the task, and use short REPL iterations before creating a larger script.

The bridge also forwards activity from the engine GUI to the agent on a later call. This includes IPython cells, console commands, opened or switched data files, plot changes, and files executed from the editor. An agent can therefore work alongside actions performed directly in the GUI.

## Setup and configuration

An ITASCA engine must be installed locally: PFC, FLAC, 3DEC, MPoint, or MassFlow. The README recommends version 9.0 or later and also lists support for PFC 6.0 and 7.0, FLAC 7.0, and 3DEC 7.0. The setup uses Python 3.10 or newer and `uv`, including its `uvx` command.

Register the server with an MCP client using `uvx itasca-mcp`, either through the client’s MCP command or a configuration entry with `command` set to `uvx` and `args` set to `["itasca-mcp"]`. The documented commands cover Claude Code, Codex, and Gemini CLI. After registration, download `addon.py` and run it from the engine’s IPython console or GUI. On later sessions, start the bridge with `import itasca_mcp_bridge` followed by `itasca_mcp_bridge.start()`.

To verify the connection, restart the MCP client and ask it to call `itasca_execute_code`. The bridge checks PyPI for a newer bridge release when `start()` runs and upgrades itself before starting.

## Tools and capabilities

ITASCA MCP Server MCP server supports these capability areas:

- Search and navigate engine command, Python API, and reference documentation.
- Select documentation by software and version.
- Execute code through an interactive REPL.
- Submit simulations as tasks and monitor their progress.
- Interrupt running tasks and review task history.
- Work with live simulations while they remain active.
- Receive selected activity from the ITASCA GUI, including plot and data-file actions.

## Limitations and notes

Documentation lookup works without the bridge, but execution tools do not. A compatible ITASCA engine installation is therefore required for simulation control and code execution. The bridge must be started again for each new engine session. The repository describes support for specific engine versions rather than every possible ITASCA release, so the selected software and version should match the installed environment.

The project documents compatibility with Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, OpenCode, toyoura-nagisa, and other MCP clients. Client configuration details may differ outside the explicitly documented setup commands.

_Full upstream README: https://allmcps.com/mcp/itasca-mcp-server/readme_