ITASCA MCP Server

社区

让 AI 智能体通过自然对话驱动 ITASCA 岩土与地质力学仿真

分类: 其他第 106 / 230
Stars: ★ 225 非常热门
传输方式: stdio（本地进程）
运行环境: Python 3.10+ · 预编译二进制
凭据: 无需凭据
许可证: MIT
最近提交: 今天
工具数: 1

55FMRS · C

itasca-mcp（ITASCA MCP Server）是一个采用 MIT 许可证的社区项目，通过 Model Context Protocol 把 AI 智能体连接到 ITASCA 的 PFC、FLAC、3DEC、MPoint 与 MassFlow。它提供 10 个工具：5 个无需 bridge 的文档工具（命令、Python API 与参考文档浏览检索，支持多引擎与多版本），以及 5 个需要 bridge 的执行工具（交互式 REPL、任务提交、进度监控、中断与历史）。它适合已安装 ITASCA 引擎、希望在自然对话中查询文档、提交并监控仿真的岩土工程用户；不适合未安装 ITASCA 引擎或期待官方支持的用户。主要风险在于执行类工具会真实运行仿真代码、bridge 会从 PyPI 自动检查并自我升级，以及模型仍可能生成不存在的命令。

最强项 · 文档质量 13/20 最弱项 · 安全与权限 9/20

可靠性

10/20

安全与权限

9/20

维护活跃度

12/20

文档质量

13/20

安装易用性

11/20

查看各项评分依据

可靠性 10/20: 静态证据显示：manifest 声明 10 个工具（5 个文档工具 + 5 个执行工具），包为 PyPI 上的 itasca-mcp 0.8.2，通过 stdio 传输，README 标明 Python 3.10+ 与 CI 徽章。但仓库仅提供 server.json 与 README，未附带真实 CI 工作流文件或已提交的测试源码，无法验证 MCP 初始化与 tools/list 握手在静态审查下可复现，也无法核对声明的 10 个工具与真实行为是否一致。执行工具依赖用户在本机 ITASCA 引擎内手动启动 bridge（addon.py / itasca_mcp_bridge.start()），错误路径、超时、引擎版本不匹配（PFC 6.0/7.0/9.0 等）等的处理均无证据。依据静态校准上限（无真实 CI + 已提交测试则 reliability 不超过 12），给予 10 分：主路径看似合理，但测试与边界情况证据薄弱。
安全与权限 9/20: 未发现红线：无恶意代码、无凭证窃取、无隐蔽外传、无默认不可逆删除/付费/部署，示例配置中不含真实令牌。执行类工具（itasca_execute_code、任务提交/中断）本质上允许代理在用户本机 ITASCA 引擎内执行任意代码并写入工程文件，属于高副作用能力，但 README 未说明任何确认机制、沙箱、范围限制或权限最小化说明；网络方面 bridge 会检查 PyPI 并自动自升级（"self-upgrades before starting"），这是一个未加确认的自动更新面，构成供应链与可控性风险；下载并粘贴 addon.py 到引擎控制台亦无完整性校验说明。主要风险可见但权限/确认/数据流披露不完整，故给 9 分，不属于红线区间。
维护活跃度 12/20: MIT 许可证明确，版本号 0.8.x 且已发布至 PyPI，README 有 CI 徽章与贡献指南，项目未归档，191 星显示有一定使用度。但静态材料中未见实际提交记录、发布节奏、issue 响应情况、依赖更新策略或安全响应渠道；自升级机制与真实维护频率均无法从所给文件核实。属于"活跃但治理/版本化存在缺口的证据状态"，给 12 分。
文档质量 13/20: 文档分层较好：英文/中文 README、前置条件、Claude Code/Codex/Gemini CLI 的注册命令与 JSON 配置示例、首次安装与每日启动流程、10 个工具的分类说明、示例提示词、开发指南与 CONTRIBUTING 链接。扣分点：工具参数（如 software、version 的取值与必填性）、返回结构、限制与配额、失败模式均未在 README 中说明；故障排查被外链到 bootstrap 指南而非就地给出；bridge 自动升级与 addon.py 的安全含义未披露。属"可用但存在隐藏假设与故障排查缺口"，给 13 分。
安装易用性 11/20: 安装路径清晰：uvx itasca-mcp 一行注册，并给出三家主流客户端命令与通用 mcpServers JSON；文档工具无需 bridge，执行工具需在引擎内运行 addon.py 或 itasca_mcp_bridge.start()。但前置条件较强且难以自动化——必须本机安装 ITASCA 商业引擎（PFC/FLAC/3DEC/MPoint/MassFlow），强依赖 uvx，且要求用户把脚本手动粘贴进引擎 IPython 控制台，属手动且脆弱的环节；无 CI/测试证据支撑安装可复现性。依据静态校准上限（无真实 CI 与测试则 setup 不超过 15），给 11 分。

静态评测 · 未实际运行收录于 2026-09-18

查看 FMRS 评分方法 →

选型与风险

能访问什么执行命令或代码

适合谁

已安装 ITASCA 引擎并希望在 AI 智能体中通过自然对话驱动仿真的岩土与地质力学工程师
需要频繁查询 PFC/FLAC/3DEC/MPoint/MassFlow 命令与 Python API 文档的用户
需要提交并监控长时间仿真任务、同时还在调试代码的研究人员
使用 Claude Code、Codex CLI、Gemini CLI 等 MCP 客户端的技术团队

不适合谁

没有安装任何 ITASCA 引擎的用户——执行类工具依赖本地引擎与 bridge，无法凭空运行仿真
期望获得 ITASCA 官方支持或官方认证的用户，该项目是社区项目
寻找浏览器、数据库或云存储类能力、而非岩土仿真的用户
希望完全免配置、开箱即用的用户——首次使用需要注册 MCP 服务器并在引擎中启动 bridge

所需权限

在本机运行 uvx 并下载、执行来自 PyPI 的 itasca-mcp 包
在 ITASCA 引擎的 IPython 控制台中执行代码以启动 bridge（addon.py 或 itasca_mcp_bridge.start()）
通过 bridge 向已运行的 ITASCA 引擎提交代码和仿真任务，并读取任务状态与结果
bridge 启动时会访问 PyPI 检查新版本并可能自我升级
读写 MCP 客户端配置文件以注册服务器

风险与副作用

执行类工具会在真实 ITASCA 引擎中运行代码与仿真，错误命令或不当参数可能产生错误结果，或消耗大量计算资源与时间
bridge 会自动检查 PyPI 并自我升级，引入的更新未经过用户逐次确认，存在供应链风险
文档浏览能减少但不能完全避免模型生成不存在的命令而导致的幻觉
长时间仿真任务若未被正确监控或中断，可能长期占用机器资源
本项目为社区项目，非 ITASCA 官方发布，兼容性与维护节奏不受上游保证

安装接入

准备工作

运行环境：Python 3.10+ · 预编译二进制

准备环境：安装 ITASCA 引擎（PFC、FLAC、3DEC、MPoint 或 MassFlow，推荐 9.0+，也支持 PFC 6.0/7.0、FLAC 7.0、3DEC 7.0），安装 uv（用于 uvx），并准备一个支持 MCP 的 AI 智能体（如 Claude Code、Codex CLI、Gemini CLI）。
注册 MCP 服务器：可使用命令行，例如 Claude Code 执行 claude mcp add itasca-mcp -- uvx itasca-mcp，或手动在 MCP 配置文件中写入 {"mcpServers":{"itasca-mcp":{"command":"uvx","args":["itasca-mcp"]}}}。
启动 bridge：下载 addon.py，然后在引擎 GUI（PFC、FLAC、3DEC 等）的 IPython 控制台中粘贴运行其内容，或在引擎 GUI 中执行该文件。
验证：重启 AI 智能体，让它调用 itasca_execute_code 来确认连接。
日常使用：每个新的引擎会话只需在引擎 IPython 控制台运行 import itasca_mcp_bridge 与 itasca_mcp_bridge.start() 即可恢复连接（start() 会检查 PyPI 上是否有更新的 bridge 版本并自行升级）。

.mcp.json

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

以 Claude Code 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

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

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add itasca-mcp -- uvx itasca-mcp

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

重启 AI 客户端后，要求其调用 itasca_execute_code 验证与 ITASCA 引擎的连接是否成功。

常见排障

执行类工具报错时，先确认 ITASCA 引擎中已运行 bridge（addon.py 或 itasca_mcp_bridge.start()），新的引擎会话需要重新启动 bridge
连接异常时确认已安装 uvx、AI 智能体已重启，并让其再次调用 itasca_execute_code 验证
文档检索结果不符合预期时检查是否传入了正确的 software 参数，以及是否需要通过 version 指定引擎版本
启动失败或版本过旧时，可在引擎 IPython 控制台中重新导入并调用 start()，让 bridge 检查并升级到新版本
更多排查建议参见 bootstrap 指南中的 Troubleshooting 章节：docs/agentic/itasca-mcp-bootstrap.md#troubleshooting

试试这样问

连接成功后，可以直接对 AI 助手这样说：

在致密试样上运行双轴压缩试验并绘制应力–应变曲线
在 FLAC3D 中建立边坡模型并求安全系数
用 3DEC 模拟节理岩体中的隧道开挖并检查洞周块体位移
模拟还在运行——在不停止任务的情况下查看当前不平衡力

工具能力 1

itasca_execute_code 写入

在 ITASCA 引擎中执行代码，用于验证 bridge 连接是否建立（README 中提及的验证方式）。

使用场景

对致密试样进行双轴压缩试验并绘制应力—应变曲线

在 FLAC3D 中建立边坡模型并求解安全系数

用 3DEC 模拟节理岩体中的隧道开挖并检查洞周块体位移

用 MPoint 模拟滑坡滑动并报告最终堆积形态

在仿真仍在运行时查询当前不平衡力而不中断任务

对比 FLAC 7.0 与 9.0 之间 zone 命令的差异

在正式编写完整脚本前，用 REPL 快速迭代和试算

支持客户端

Claude Code

Codex

Gemini CLI

GitHub Copilot CLI部分支持

OpenCode部分支持

依据项目文档列出，未经本站实测。

详细介绍

itasca-mcp 是一个基于 Model Context Protocol 的服务器，把 AI 智能体连接到 ITASCA 的地质力学仿真软件——PFC、FLAC、3DEC、MPoint 与 MassFlow。智能体可以浏览并检索所选引擎的命令文档、Python API 与参考文档，提交长时间运行的仿真任务、监控进度、中断任务并查看任务历史，还能在仿真运行期间通过交互式 REPL 执行代码而不打断任务。文档类工具无需 bridge；执行类工具需要在 ITASCA 引擎内启动 bridge（通过 addon.py 或 itasca_mcp_bridge.start()）。软件通过必需的 software 参数选择，命令文档支持通过 version 参数切换版本（PFC 6.0/7.0/9.0、FLAC 7.0/9.0、3DEC 7.0/9.0）。该项目以 PyPI 包 itasca-mcp 分发，使用 uvx 以 stdio 方式运行，采用 MIT 许可证，属于社区项目而非 ITASCA 官方产品。