适合谁
- 已安装 ITASCA 引擎并希望在 AI 智能体中通过自然对话驱动仿真的岩土与地质力学工程师
- 需要频繁查询 PFC/FLAC/3DEC/MPoint/MassFlow 命令与 Python API 文档的用户
- 需要提交并监控长时间仿真任务、同时还在调试代码的研究人员
- 使用 Claude Code、Codex CLI、Gemini CLI 等 MCP 客户端的技术团队
I
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 自动检查并自我升级，以及模型仍可能生成不存在的命令。
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 官方产品。
工具能力
itasca_execute_code
在 ITASCA 引擎中执行代码，用于验证 bridge 连接是否建立（README 中提及的验证方式）。
安装接入
- 准备环境：安装 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 版本并自行升级）。
claude_desktop_config.json
{"mcpServers":{"itasca-mcp":{"command":"uvx","args":["itasca-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 官方发布，兼容性与维护节奏不受上游保证
常见排障
- 执行类工具报错时，先确认 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
使用场景
对致密试样进行双轴压缩试验并绘制应力—应变曲线
在 FLAC3D 中建立边坡模型并求解安全系数
用 3DEC 模拟节理岩体中的隧道开挖并检查洞周块体位移
用 MPoint 模拟滑坡滑动并报告最终堆积形态
在仿真仍在运行时查询当前不平衡力而不中断任务
对比 FLAC 7.0 与 9.0 之间 zone 命令的差异
在正式编写完整脚本前，用 REPL 快速迭代和试算
支持客户端
Claude Code完整支持
Codex CLI完整支持
Gemini CLI完整支持
GitHub Copilot CLI部分支持
OpenCode部分支持