Paraview MCP Server

全景mcp服务器

通过模型上下文协议使用AI助手控制ParaView。

paraview-mcp-server 是一个双进程桥接器，可以让Claude Desktop等人工智能助手 Codex CLI在ParaView中打开数据集、应用过滤器、颜色数据和导出屏幕截图 使用自然语言。

______________________________________________________________________

运作原理

MCP Client (Claude Desktop, Codex CLI, …)
      ⇅  stdio
paraview-mcp-server            ← thin MCP server, defines 31 tools
      ⇅  JSON / TCP localhost:9876
ParaView bridge (pvpython)     ← dispatches commands with paraview.simple
      ⇅
paraview.simple / servermanager

• 这 MCP服务器 是一个普通的Python包。它通过stdio与MCP通信并转发

每个工具调用都是通过本地TCP套接字向网桥发出的JSON请求。

• 这 桥 跑进去 pvpython。它接收JSON命令，并通过以下方式发送它们

命令注册表，调用 paraview.simple，并返回JSON结果。

• 这两个进程在导入时都不依赖于对方的代码。
• A. 无头pvpython执行器 让MCP服务器在单独的环境中运行脚本

pvpython 用于长时间运行或异步工作流的流程（不需要桥接）。

看 docs/architecture.md 对于完整的图、协议参考， 以及工具名称空间表。

______________________________________________________________________

快速开始

1.安装MCP服务器

git clone https://github.com/djeada/paraview-mcp-server.git
cd paraview-mcp-server
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .

2.启动ParaView桥

在具有以下功能的终端中 pvpython 上 PATH:

pvpython scripts/start_paraview_bridge.py
# → ParaView bridge ready on 127.0.0.1:9876

网桥监听来自MCP服务器的JSON命令。

3.在AI客户端注册MCP服务器

克劳德桌面 --添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "paraview": {
      "command": "/absolute/path/to/.venv/bin/paraview-mcp-server"
    }
  }
}

Codex CLI：

codex mcp add paraview -- /absolute/path/to/.venv/bin/paraview-mcp-server

______________________________________________________________________

示例提示

一旦两个进程都运行并且配置了MCP客户端：

• *“列出当前ParaView会话中的所有源。”*
• *“打开 /data/disk_out_ref.ex2."*
• *“通过磁盘数据集的X=0创建切片。”*
• *“按压力为数据集着色。”*
• *“将屏幕截图保存到 /tmp/view.png."*
• *“对等值线为0.5和1.0的压力应用轮廓过滤器。”*
• *“将相机设置在\[10,5,5\]位置，查看原点。”*
• *“将背景设置为从白色到深蓝色的渐变。”*
• *“将动画导出到 /tmp/anim.avi."*

______________________________________________________________________

工具参考（31个工具）

场景/会话

数据加载

过滤器——基本

过滤器--高级

显示/着色

摄像头/视图

出口

Python执行

作业管理

______________________________________________________________________

Python执行

paraview_python_exec 是需要超过固定值的工作流的逃生口 工具组。脚本在桥接进程中运行，其中 paraview.simple 已导入。

参数：

执行命名空间：

例子：

# Open a file and create a slice
src = pvs.OpenDataFile(args["filepath"])
view = pvs.GetActiveViewOrCreate("RenderView")
pvs.Show(src, view)
filt = pvs.Slice(Input=src)
filt.SliceType.Origin = [0, 0, 0]
filt.SliceType.Normal = [1, 0, 0]
pvs.Show(filt, view)
pvs.ResetCamera(view)
__result__ = {"done": True}

看 docs/python-execute-design.md 对于整个设计， 模式引用和更多示例。

______________________________________________________________________

异步作业执行

对于长时间运行的管道，请使用 paraview_python_exec_async:

1. 开始工作→ 回报 job_id 立即
2. 投票与 paraview_job_status → check status 领域
3. 取消 paraview_job_cancel 如有需要

异步作业在单独的无头中运行 pvpython 过程通过 HeadlessPvpythonExecutor.

______________________________________________________________________

安全模型

• 模块堵塞 --脚本无法导入 subprocess, shutil, socket, ctypes,

multiprocessing, webbrowser，或几个面向网络的stdlib模块。

• 输出边界 --stdout/stderr的上限为 50 KB.
• 协作超时 --默认每个脚本执行30秒。
• 脚本路径验证 --可以选择将执行限制在批准的根目录。
• 桥在里面 pvpython 具有与本地ParaView会话相同的信任级别。
• 这是一个本地桌面自动化工具，而不是公共的API沙箱。

______________________________________________________________________

发展

安装开发依赖项

pip install -e ".[dev]"

运行测试

pytest tests/

测试做 不 需要安装ParaView。命令处理程序测试补丁 _import_pv 带着一个 MagicMock 这模仿了 paraview.simple API

发送原始桥接命令（用于调试）

python scripts/paraview_bridge_request.py scene.get_info
python scripts/paraview_bridge_request.py source.open_file --params '{"filepath":"/data/disk.vtu"}'
python scripts/paraview_bridge_request.py export.screenshot --params '{"filepath":"/tmp/shot.png"}'

______________________________________________________________________

项目结构

paraview-mcp-server/
├── pyproject.toml
├── src/
│   └── paraview_mcp_server/
│       ├── __init__.py          # Re-exports main()
│       ├── server.py            # FastMCP stdio server (31 tools)
│       └── headless.py          # Headless pvpython executor + job manager
├── bridge/
│   ├── __init__.py
│   ├── server.py                # TCP socket bridge server
│   ├── command_handler.py       # Command registry + paraview.simple handlers (27 commands)
│   └── execution.py             # python.execute helper with safety controls
├── scripts/
│   ├── start_paraview_bridge.py
│   ├── paraview_bridge_request.py
│   └── library/                 # Reusable pvpython snippets
│       ├── open_dataset.py
│       ├── create_slice.py
│       ├── create_contour.py
│       ├── color_by.py
│       ├── reset_camera.py
│       └── save_screenshot.py
├── docs/
│   ├── architecture.md
│   └── python-execute-design.md
└── tests/
    ├── test_server.py           # 31 tools, connection, headless, async jobs
    ├── test_protocol.py         # Wire encoding, fake bridge integration
    └── test_command_handler.py  # All 27 handlers + safety controls

______________________________________________________________________

许可证

麻省理工学院——见 许可证.