Allows interaction with BIOVIA Materials Studio, providing tools for modeling, simulation (Forcite, DMol3, CASTEP), GUI queue, and job monitoring via Dashboard.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MS-MCP Run a Forcite geometry optimization on the current structure."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
面向 Windows 与 BIOVIA Materials Studio 的外部 Model Context Protocol（MCP）服务器。它让 Codex 或其他 MCP 客户端通过官方 MaterialsScript 运行时执行建模、Forcite、DMol3、CASTEP、GUI 队列和结果读取，并提供本地 Dashboard。
当前版本：
0.2.0。项目不是 BIOVIA/Dassault Systèmes 官方产品；使用前请确认 Materials Studio 许可证及 MaterialsScript 组件可用。
检查 Materials Studio、RunMatScript.bat、工作区和会话状态。
创建/导入结构，维护当前 GUI 文档，并执行常用结构编辑。
执行 Forcite、DMol3、CASTEP 任务与预设工作流。
通过可选的 Materials Studio GUI 循环把脚本送入当前打开的项目。
从受限 HTTPS 白名单下载 CIF，并限制响应大小。
准备远程 CASTEP 任务，Dashboard 可通过 SSH 只读监控 Gateway 作业目录。
所有生成文件默认限制在独立工作区；任意 MaterialsScript 和外部输入默认关闭。
Related MCP server: MoonRay MCP
Windows 10/11（64 位）。
BIOVIA Materials Studio，且已安装 MaterialsScript；必须能找到：
MS_INSTALL_ROOT\etc\Scripting\bin\RunMatScript.bat。
Node.js 20 或更高版本，包含 npm.cmd。
Codex 或其他支持 stdio MCP 的客户端。
可选：Windows OpenSSH Client（只在远程 Dashboard 监控时使用）。
下载 Release 压缩包或克隆仓库后，不要把项目放入随后会删除或改名的临时目录。推荐路径如 C:\Tools\MS-MCP。
双击 Configure-MS-MCP.bat，逐项确认 Node、Materials Studio、工作区等路径。
双击 Install-MS-MCP.bat，以 npm ci 安装锁定依赖并检查发布文件。
双击 Test-MS-MCP.bat，验证路径、安全默认值和 MCP stdio 通信。
打开生成的 config\codex-ms-mcp.local.toml，把完整内容合并到 %USERPROFILE%\.codex\config.toml。
完全退出并重启 Codex，在 MCP 列表中确认 MS-MCP 可用。
完整逐步说明、路径示例和安装后修改方法见 安装与配置指南。
Configure-MS-MCP.bat 是唯一推荐的本机配置入口，内部调用 PowerShell 完成验证和安全写入：
config\ms-mcp.local.bat：供启动、测试、Dashboard、GUI 循环和 SSH 脚本统一读取。
config\codex-ms-mcp.local.toml：供复制到 Codex 的 MCP 配置块。
这两个文件包含本机绝对路径，已由 .gitignore 排除，不能上传 GitHub。仓库只保留不含真实机器信息的 config\ms-mcp.example.bat、.mcp.example.json 和 codex-ms-mcp.toml.example。
变量/配置 | 含义 | 何时必须修改 |
|
| Node 安装位置变化或换电脑 |
| 与 Node 配套的 | Node 安装位置变化 |
| Materials Studio 安装根目录 | 版本、盘符或安装目录变化 |
| 可写的独立任务工作区 | 换电脑、迁移数据或调整存储盘 |
MCP | 本仓库 | 仓库移动、改名或重新解压 |
MCP | 本仓库根目录 | 仓库移动、改名或重新解压 |
| 已有 Materials Studio 模型目录 | 仅使用 Chapter 3 同步时设置 |
|
| 仅使用远程监控时设置 |
| SSH 私钥绝对路径 | 使用非默认密钥或用户目录变化 |
| Linux Gateway 作业根目录 | 远端版本、用户或 Gateway 根目录变化 |
仓库移动后不要逐个修改启动脚本；重新运行 Configure-MS-MCP.bat，再用新生成的 TOML 更新 Codex 即可。
正常情况下由 Codex 按 TOML 自动启动。调试时可运行：
Run-MS-MCP.bat该进程使用 stdio 协议，命令窗口看似等待输入是正常现象；不要向 stdout 添加日志。
双击 Start-MS-MCP-Dashboard.bat，浏览器打开 http://127.0.0.1:4877/。端口可在重新配置时修改。MCP 也可在后台启动 Dashboard，但默认不会强制打开浏览器。
需要登录 Windows 后自动启动时，先完成配置与测试，再运行 Install-Dashboard-Autostart.bat。快捷方式使用相对仓库定位；若移动仓库，重新安装自启快捷方式。
要把任务写入当前由用户打开的 Materials Studio 项目时：
先运行 Configure-MS-MCP.bat。
在 Materials Studio 中打开目标项目。
从 Materials Studio 的脚本界面运行 materialscript\mcp_loop_gui.pl；或在正确的 Materials Studio 会话条件下使用 materialscript\start_mcp_loop.bat。
队列位于 %MS_MCP_WORK_ROOT%\.mcp-queue，停止标记为 .mcp-queue\stop。
GUI 循环必须在 Materials Studio GUI 环境中运行，不能把普通 RunMatScript.bat 进程误当成已打开项目的 GUI 上下文。
重新运行 Configure-MS-MCP.bat，填写 user@host 和远程 Gateway jobs 路径，然后运行 Setup-Dashboard-SSH.bat。脚本创建独立 Ed25519 密钥、把公钥加入远端 authorized_keys，并验证非交互登录。Dashboard 不保存服务器密码。
这只配置作业目录监控；Materials Studio Gateway、队列、许可证和计算核数仍需在 Materials Studio Job Control 中按实际服务器配置。
MS_MCP_ALLOW_ARBITRARY_SCRIPT=0：禁用任意 MaterialsScript。
MS_MCP_ALLOW_GUI_QUEUE=1：允许结构化 GUI 队列工具。
MS_MCP_ALLOW_EXTERNAL_INPUTS=0：禁止读取工作区外输入。
CIF 仅允许配置的 HTTPS 主机，默认最大 10 MiB。
Dashboard 默认只监听 127.0.0.1；写操作默认关闭。启用写操作时必须配置至少 24 字符令牌。
工作区路径经边界与 junction/symlink 检查，防止任务越界写入。
更详细的部署原则见 LOCAL-HARDENING.md，漏洞报告见 SECURITY.md。
在已经加载正确环境变量的终端中：
npm ci
npm run check
npm run smoke
npm run security-smoke
npm run mcp-smokeWindows 用户直接运行 Test-MS-MCP.bat 更简单，它会加载生成的本机配置。涉及真实 Forcite/DMol3/CASTEP 的计算仍应在授权的测试模型和服务器上单独验证。
MS-MCP/
├─ src/ MCP 服务器与 MaterialsScript 生成逻辑
├─ materialscript/ Materials Studio GUI 循环
├─ GUI-Dashboard/ 本地 Dashboard
├─ scripts/ 验证、解析、同步与远程准备脚本
├─ config/ 示例配置；本机生成配置不会上传
├─ docs/ 安装与配置文档
├─ examples/ 示例输入
├─ Configure-MS-MCP.bat 分步配置入口
├─ Install-MS-MCP.bat 锁定依赖安装
├─ Test-MS-MCP.bat 完整本机验证
└─ Run-MS-MCP.bat 手动 stdio 启动入口GitHub 上传清单与排除项见 RELEASE-FILES.md。
找不到 RunMatScript.bat：MS_INSTALL_ROOT 填得太上层或太下层。应直接指向包含 etc\Scripting 的 Materials Studio 版本目录，然后重新配置。
移动仓库后 Codex 启动失败：重新运行配置 BAT，并替换 Codex TOML 中旧的 command、args、cwd 与环境路径。
Node 可用但 npm.cmd 不存在：安装完整的 Node.js Windows 发行版，而不是只复制 node.exe。
Dashboard 可打开但没有结构/作业：先检查工作区与当前 session；远程作业还需要 SSH target、key 和 jobs root 三项同时有效。
MCP 修改不到当前 GUI 项目：确认 GUI 循环是在目标 Materials Studio 会话中运行，而不是只启动了独立 MaterialsScript 进程。
提交 Issue/PR 前请阅读 CONTRIBUTING.md，不要提交许可证文件、真实结构数据、服务器地址、私钥、本机配置或计算输出。项目采用 MIT License。
本项目初始代码基于 shenghhe-svg/shengh_he，感谢原作者的工作与分享。
安装、配置及使用视频教程可在抖音搜索：抖音号 Au.Tom，昵称 Dr.小叶。
独立的上游来源与教程声明见 NOTICE.md。
Run a CASTEP task or preset calculation on an input document located under the MS-MCP work root. Presets include Energy, GeometryOptimization, Frequency/phonons, DOS, band structure, charge density, and density difference.
Inputs: inputDocument (required), task, cores, project, +1 more.
Return an MCP server config snippet that can be pasted into Codex settings.
Inputs: no named parameters.
Create a standalone molecule/crystal document from explicit atoms and bonds using MaterialsScript. For the already-open GUI project, prefer ms_gui_create_current to avoid duplicate GUI documents.
Inputs: atoms (required), documentName (required), bonds, project.
Run a Forcite task on an input document located under the MS-MCP work root.
Inputs: inputDocument (required), task, cores, project, +1 more.
Add vacuum to the current GUI periodic document in place only when the user explicitly asks for vacuum. For an already-built 3D cell, extend_lattice increases the chosen lattice length while preserving Cartesian atom positions; for 2D surfaces, vacuum_slab uses CrystalBuilder VacuumSlab.
Inputs: thickness (required), axis, mode, exportFile, +5 more.
Queue a MaterialsScript body that modifies the current GUI document in place. Use this for 'on this molecule...' edits.
Inputs: body (required), save, label, exportFile, +2 more.
Queue a CASTEP calculation on the current GUI document. Supports Energy, GeometryOptimization, phonon/frequency, DOS, band structure, charge density, and density difference presets.
Inputs: cores, quality, exportFile, documentName, +5 more.
Cleave a surface from the current GUI crystal and build a vacuum slab through Materials Studio SurfaceBuilder + CrystalBuilder. Use only when the user explicitly asks to cleave/build a surface or create a vacuum slab by the manual surface workflow.
Inputs: slabThickness (required), vacuumThickness (required), h, k, +10 more.
Create or replace the current GUI document as a periodic crystal/unit cell from lattice parameters and atom coordinates. Before using this for a new crystal, first try ms_gui_find_cif_import_current against open CIF sources; use manual construction only when no reliable open CIF is found or the user provides credentials/API access for a restricted source. Do not add vacuum here unless the user explicitly requested vacuum in the initial cell parameters.
Inputs: a (required), b (required), c (required), atoms (required), +13 more.
Create or replace the current GUI document from a MaterialsScript body. Before using this for a new structure, first try ms_gui_find_cif_import_current against open CIF sources; use manual construction only when no reliable open CIF is found or the user provides credentials/API access for a restricted source. By default it reuses the existing current/same-name document and rebuilds it in place to avoid duplicate .xsd files.
Inputs: body (required), documentName (required), forceNew, exportFile, +1 more.
Queue a DMol3 GeometryOptimization on the current GUI document and organize calculation outputs under a dedicated calculation name/folder.
Inputs: cores, charge, quality, exportFile, +5 more.
Queue a basic molecule-building edit on the current GUI document, such as adding/deleting bonds, changing an atom element, adding/deleting atoms, recalculating bonds, Clean, or AdjustHydrogen.
Inputs: x, y, z, atom, +13 more.
Queue a Forcite GeometryOptimization on the current GUI document using a manual-like calculation folder layout.
Inputs: cores, quality, exportFile, forcefield, +7 more.
Build a supercell from the current GUI periodic document in place, using Materials Studio BuildSuperCell.
Inputs: a, b, c, surface2D, +4 more.
Prepare independent native CASTEP geometry-optimization jobs or compatibility Script Job drivers. The default native_castep mode stages one XSD plus one CASTEP settings document per structure/spin task for separate submission from the CASTEP Calculation dialog, giving each calculation its own CASTEP Job Control entry and native convergence graphs.
Inputs: tasks (required), batchName, commonSettings, submissionMode, +1 more.
Ensure and return the current MS-MCP task/session output directory under the workspace.
Inputs: no named parameters.
Set lattice parameters on the current GUI crystal document in place.
Inputs: a, b, c, beta, +5 more.
Get the stateful GUI session target: current document, current exported file, last job, and history.
Inputs: no named parameters.
List files under the MS-MCP work root.
Inputs: subdir, maxFiles.
Inspect the optional MS-MCP GUI queue folders.
Inputs: no named parameters.
Read the local preparation markers, submission receipt, and downloaded result summary available for a remote CASTEP batch.
Inputs: batchName (required).
Record one Materials Studio Job Control receipt. For native_castep preparation, call this once per calculationName after submitting its XSD from the CASTEP Calculation dialog.
Inputs: jobId (required), gateway (required), batchName (required), status, +6 more.
Run a MaterialsScript Perl script through RunMatScript. Disabled by default unless MS_MCP_ALLOW_ARBITRARY_SCRIPT=1.
Inputs: script (required), args, name, cores, +1 more.
Check Materials Studio paths, RunMatScript availability, and MS-MCP workspace.
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 24 tools
The ms_gui_*_current tools are mostly distinct, but ms_gui_apply_current overlaps with ms_gui_edit_current and ms_run_materialscript, and ms_castep/ms_gui_castep_current plus ms_forcite/ms_gui_forcite_optimize_current pair off by context rather than purpose. Descriptions help resolve most ambiguity, but a few boundaries remain blurry.
Names are consistently snake_case and the ms_gui_<verb>_current pattern is recognizable, but non-GUI tools mix verb_noun names, noun-only status names, and bare product names like ms_castep and ms_forcite. The convention is readable but not uniform.
With 24 tools, this server sits in the heavy 16-25 range, though the breadth covers environment checks, script execution, GUI structure editing, multiple simulation engines, and remote batch tracking. A smaller, more focused set would likely be easier for agents to navigate.
The descriptions repeatedly instruct agents to first try ms_gui_find_cif_import_current, but that tool is not present in the server, creating a dead end in the structure-creation workflow. There is also no general local job status or result retrieval tool for the non-remote CASTEP and Forcite runs.
Hosted MCP server for task-first delegation to remote workstations and workers.
MCP server for aerospace calculations: orbital mechanics, ephemeris, DSN operations, ...
MCP Server for an Agent Task Marketplace
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
