Skip to main content
Glama

itasca-mcp

English | 简体中文

CI PyPI Downloads GitHub stars License: MIT Python 3.10+

itasca>model new ;now, with LLM.

itasca-mcp connects AI agents to ITASCA's geomechanics simulation software — PFC, FLAC, 3DEC, MPoint, and MassFlow — through the Model Context Protocol. Browse documentation, run simulations, and execute code, all through natural conversation.

itasca>model solve ;LLM solves.

itasca-mcp demo

Tools (7)

2 documentation tools — browse by path and search by keywords across the selected engine's commands, Python API, FISH intrinsics, and reference docs. No bridge required.

5 execution tools — interactive REPL, task submission, progress monitoring, interruption, and history. Requires bridge.

Related MCP server: mcp-server-terminal

Example Prompts

  • "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"

  • "The simulation is still running, check the current unbalanced force without stopping it"

  • "Look up the plot commands in the docs, then plot the contact force chains of the current model"

  • "The command I just typed in the console doesn't seem right, take a look"

First-time Setup

Prerequisites

  • An ITASCA engine installed — PFC, FLAC, 3DEC, MPoint, or MassFlow. The Subscription release (9.0+) is recommended; PFC 6.0 / 7.0, FLAC 7.0, and 3DEC 7.0 are also supported.

  • uv installed (for uvx)

  • An AI agent — Claude Code, Codex CLI, Gemini CLI, or any MCP-capable client

Copy this to your AI agent and let it self-configure:

Fetch and follow this bootstrap guide end-to-end:
https://raw.githubusercontent.com/yusong652/itasca-mcp/main/docs/agentic/itasca-mcp-bootstrap.md

Manual Setup

1. Register the MCP server with your agent.

Most agents register it with a single command:

# Claude Code
claude mcp add itasca-mcp -- uvx itasca-mcp

# Codex / Codex-cli
codex mcp add itasca-mcp -- uvx itasca-mcp

# Gemini CLI
gemini mcp add itasca-mcp uvx itasca-mcp

Or fill in the MCP config file manually:

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

2. Install the bridge into the engine's Python. In a terminal, run pip with the interpreter bundled in the engine's install directory (exe64/python310 for the Subscription release, exe64/python36 for 6.0/7.0). With the default install locations:

# Subscription (latest)
& "C:\Program Files\Itasca\Itasca Software Subscription\exe64\python310\python.exe" -m pip install --user -U itasca-mcp-bridge

# 7.0 (FLAC3D shown)
& "C:\Program Files\Itasca\FLAC3D700\exe64\python36\python.exe" -m pip install --user -U itasca-mcp-bridge

3. Start the bridge in the engine's IPython console (PFC, FLAC, 3DEC, ...):

import itasca_mcp_bridge
itasca_mcp_bridge.start()

If pip cannot reach PyPI, paste the contents of addon.py into the engine's IPython console instead: it installs the bridge (with a mirror fallback) and starts it in one go.

Verify

Restart your AI agent and ask it to call itasca_execute_code to verify the connection.

Daily Startup

Once first-time setup is done, each new engine session only needs the bridge re-started — run this in the engine's IPython console and you're back online:

import itasca_mcp_bridge
itasca_mcp_bridge.start()

start() checks PyPI for a newer bridge release and self-upgrades before starting. The MCP client config persists.

Features

  • Multi-engine, multi-version corpus - command, Python API, and reference docs for PFC, FLAC, 3DEC, MPoint, and MassFlow across engine versions (PFC: 6.0/7.0/9.0, FLAC: 7.0/9.0, 3DEC: 7.0/9.0), selected via the software and version parameters

  • Documentation agents can navigate - agents browse the engine command tree to discover capabilities and boundaries, reducing hallucinated commands, with plot item reference docs supplementing the official documentation

  • Live REPL alongside running tasks - execute code while a simulation is running: check model state and intermediate results without stopping the task; also useful for quick iteration before writing a full script

  • Task lifecycle management - submit long-running simulations, monitor progress, interrupt running tasks, and browse task history

  • Human-agent interaction in the GUI - the agent follows what you do in the engine GUI (the code and commands you run, the plots and data files you open or edit, the dialogs that come up), and the files it runs or changes show up in your Project pane and editor, so you and the agent work on the same model at the same time

  • Agent-started bridge - an AI agent can start the bridge itself through the engine's console.exe

  • Multi-client compatible - works with Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, OpenCode, toyoura-nagisa, and other MCP clients

Troubleshooting

See Troubleshooting in the bootstrap guide.

Development

See Developer Guide: Install and Run from Source.

Contributing

PRs and issues are welcome! See CONTRIBUTING.md for where changes land and how the documentation corpus is structured, and the Developer Guide for the source install.

License

MIT - see LICENSE.

Available Tools

7 tools
itasca_browse_docA

Browse ITASCA documentation by path, like ls + cat over one documentation tree.

source picks the tree: commands (Itasca command syntax and keywords), python_api (the itasca Python SDK), fish (FISH intrinsic functions: name, signature, which versions have it, whether it is 2D or 3D only), reference (contact/constitutive/joint model properties, range elements, plot items). Each level lists what is below it, so start at the top of a tree when unsure and descend.

Use itasca_query_doc when you only have keywords; its results are paths for this tool.

Inputs: source (required), software (required), path, version. Returns: object

itasca_check_task_statusA

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.

Inputs: task_id (required), limit, filter, skip_newest, +1 more. Returns: object

itasca_execute_codeA

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.

Inputs: code (required), timeout. Returns: object

itasca_execute_taskA

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.

Inputs: description (required), entry_script (required). Returns: object

itasca_interrupt_taskA

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.

Inputs: task_id (required). Returns: object

itasca_list_tasksA

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.

Inputs: limit, skip_newest. Returns: object

itasca_query_docA

Search ITASCA documentation by keywords, like grep; every hit carries a path for itasca_browse_doc.

Without source it searches commands, python_api, fish and reference together, so 'ball pos' shows the FISH intrinsic and the Python method side by side. With source it searches one tree and adds that tree's hints (available categories or namespaces, SDK fallback hints) when nothing matches.

Inputs: query (required), software (required), limit, source, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool occupies a clearly distinct slot: query_doc (keyword search) vs browse_doc (path traversal), execute_code (synchronous inline) vs execute_task (async script file), and the task trio check_task_status / interrupt_task / list_tasks. The descriptions explicitly contrast the potentially confusable pairs and cross-reference each other for next steps, leaving no room for misselection.

    Naming Consistency5/5

    Every tool uses the same itasca_ prefix plus a verb_noun pattern (browse_doc, query_doc, execute_code, execute_task, check_task_status, interrupt_task, list_tasks). The lifecycle tools even share the _task suffix, making the grouping obvious from names alone.

    Tool Count5/5

    Seven tools is tightly scoped for an engine bridge: two for docs, two for code execution, three for async task lifecycle. Nothing feels redundant and no tool is a trivial wrapper, since each has a separate mechanism (sync/async, poll/interrupt/history).

    Completeness4/5

    The surface covers docs lookup, sync and async execution, plus full task lifecycle including status output, interruption, and persisted history — a solid closed loop. Minor gaps remain: there is no dedicated tool to write/upload the script file that execute_task consumes, and no way to wait/join on a task or prune task history, though both are workable via execute_code or polling.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server enabling AI agents to interact with terminal applications through structured Terminal State Tree representation. Works with any AI assistant that supports the Model Context Protocol.
      103 npm
      21
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      yade-mcp connects AI agents to YADE — the open-source discrete element method engine — through the Model Context Protocol. Browse API docs, run simulations, and execute code, all through natural conversation.
      7
      86 PyPI
      15
      MIT