AI导哈

Substance Designer MCP集成

Substance Designer MCP集成是Adobe Substance 3D Designer的首个MCP（模型上下文协议）集成，允许通过任何MCP兼容的AI客户端（如Claude Code、Claude Desktop、Cursor）控制Substance Designer，创建图形、构建节点、连接节点、设置参数，并通过单个提示生成完整的PBR材质图形。

  • by matthieuhuguet
  • Python
  • 本地部署
  • 61 星标
  • 更新于
在 GitHub 查看 matthieuhuguet/substance-designer-mcp

使用说明

物质设计师MCP

Adobe Substance 3D Designer的第一个MCP（模型上下文协议）集成。

从任何兼容MCP的AI客户端（Claude Code、Claude Desktop、Cursor）控制物质设计器——创建图形、构建节点、连接它们、设置参数、从单个提示生成完整的PBR材料图。

它做什么

  • 自然语言→ SD图：“制造开裂的混凝土材料”→ 44-节点PBR图，包括高度、法线、粗糙度、AO、基色、金属输出
  • 79种内置材料配方：使用与专业SD艺术家相同的节点架构的专业级材料
  • 16个MCP工具：在一次调用中获取场景信息、创建/删除图形、创建节点、连接节点、设置参数、构建完整材质
  • 库节点支持：云、细胞、Perlin噪声、多边形、边缘检测、洪水填充、多向扭曲等。
  • 线程安全：所有SD API调用通过Signal/Slot排队连接发送到Qt主线程

建筑

AI Client (Claude / Cursor)
        │  stdio (MCP protocol)
        ▼
sd_mcp_bridge.py  (FastMCP server, Python 3.12)
        │  TCP localhost:9881 (length-prefix framing)
        ▼
SD Plugin __init__.py  (Python 3.11, runs inside SD)
        │  sd.api
        ▼
Adobe Substance 3D Designer 15.x

网桥和插件通过简单的长度前缀成帧协议进行通信： [4-byte big-endian length][JSON payload]每个命令都使用一个新的TCP套接字——没有持久连接，没有过时状态。

需求

  • Adobe Substance 3D Designer 15.x （15.0.3测试）
  • Python 3.12+ 桥（通过管理 紫外线)
  • 紫外线 包管理器： pip install uv 或 winget install astral-sh.uv
  • MCP兼容客户端： 克劳德代码, 克劳德桌面版，或 光标

安装

步骤1--安装SD插件

复制 plugin/ 将文件夹内容保存到SD用户脚本目录：

窗户：

%USERPROFILE%\Documents\Adobe\Adobe Substance 3D Designer\python\sduserplugins\sd_mcp_plugin\

目录必须包含：

sd_mcp_plugin/
├── __init__.py    ← main plugin (TCP listener, all MCP tools)
└── recipes.py     ← 79 material recipes

SD自动加载来自的所有插件 sduserplugins/ 在启动时。无需额外配置。

步骤2——安装网桥服务器

cd server/
uv sync   # installs mcp[cli] into .venv

或者使用pip：

pip install "mcp[cli]>=1.4.1"

步骤3--配置MCP客户端

克劳德代码 (~/.claude/settings.json):

{
  "mcpServers": {
    "substance_designer": {
      "command": "C:\\Users\\YOUR_USERNAME\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--directory",
        "C:\\PATH\\TO\\substance-designer-mcp\\server",
        "python",
        "sd_mcp_bridge.py",
        "--port",
        "9881"
      ]
    }
  }
}

看 config/ Claude Desktop和Cursor示例的文件夹。

步骤4--在AI客户端之前启动SD

SD必须在MCP网桥启动之前运行。 该插件在SD启动时绑定TCP端口9881。如果Claude/Cursor启动时SD未运行，则网桥将无法连接。

用法

连接后，您可以要求您的AI客户端：

Build a weathered steel material with surface oxidation

Create a cliff heightmap with high detail and disorder

Make a new graph called MyRock, add a clouds node and a slope blur, connect them

List all available material recipes

可用的MCP工具

工具 说明
get_scene_info 列出所有打开的包和图表
create_graph 创建新的合成图
get_graph_info 获取图中的所有节点和连接
list_node_definitions 搜索可用节点类型
create_node 创建原子节点（混合、级别、模糊等）
create_instance_node 创建库节点（云、细胞、Perlin等）
create_output_node 创建PBR输出（基色、法线、高度等）
connect_nodes 通过端口连接两个节点
disconnect_nodes 删除连接
set_parameter 设置节点参数
get_node_info 获取节点的端口和参数
delete_node 删除节点
move_node 重新定位节点
duplicate_node 复制原子节点
delete_graph 从包中删除图形
open_graph 在SD编辑器中打开图形
save_package 将包保存到磁盘
execute_sd_code 在SD的上下文中执行任意Python
build_material_graph 在一次通话中构建完整的PBR材料
build_heightmap_graph 在一次调用中构建一个仅包含高度图的图形
list_recipes 列出所有79种可用的材料配方
get_recipe_info 获取特定食谱的详细信息
apply_recipe 将配方应用于现有图形

材料配方

build_material_graph(graph_name="MySteel", recipe_name="pro_steel")
# → 37-node PBR graph: height + normal + roughness + AO + baseColor + metallic

build_heightmap_graph(graph_name="CliffHM", style="cliff", detail_level=3, scale=5.0, disorder=0.5)
# → 9-node heightmap graph

专业配方（37-44个节点，专业架构）： pro_granite, pro_limestone, pro_sandstone, pro_basalt, pro_slate, pro_steel, pro_iron, pro_copper, pro_concrete, pro_concrete_aged, pro_concrete_smooth

核心材料： steel, iron, copper, gold, silver, aluminum, brass, granite, marble, sandstone, limestone, slate, basalt, wood, wood_oak, moss, bone, leather, fabric_cotton, fabric_silk, fabric_wool, fabric_denim, fabric_burlap, sand, mud, gravel, clay, soil, ice, snow, frost, water, diamond, ruby, sapphire, emerald, amethyst, concrete, brick, lava, asphalt, plaster, tile, painted_metal, carbon_fiber, terracotta, obsidian, ...

高度图样式： cliff, rock, sand, cracked, mud, mountain, cobblestone, terrain

关键规则（SD 15.x）

这些是SD 15.x API的硬约束-违反它们挂起或崩溃SD：

  • 一次调用一个工具 --从不并行调用SD工具
  • SDUsage.sNew() 永久悬挂SD 15 --已从插件中删除
  • newNode(unknown_definition) 永久悬挂SD 15 --插件在调用前进行验证
  • arrange_nodes() 销毁所有连接 --使用 move_node() 相反
  • 库节点输出为 从不 "unique_filter_output" --总是打电话 get_node_info 第一
  • directionalwarp 扭曲贴图端口= "inputintensity" （不是 inputgradient)
  • 中的端口ID错误 connect_nodes =crash--插件在调用SD之前进行验证

已知库节点端口（SD 15.0.3）

节点 输出 关键输入
clouds_2 output scale, disorder
cells_1 output scale, disorder
perlin_noise output scale, disorder
polygon_2 output Sides, Scale, Gradient
gradient_linear_1 Simple_Gradient Tiling, rotation
gradient_axial output point_1, point_2
slope_blur_grayscale_2 Slope_Blur Samples, Source, Effect
blur_hq_grayscale Blur_HQ Intensity, Source
non_uniform_blur_grayscale Non_Uniform_Blur Intensity, Anisotropy, Source
edge_detect output edge_width, tolerance, input
flood_fill output mask
flood_fill_to_gradient_2 output angle, input, angle_input
flood_fill_to_grayscale output luminance_random, input
multi_directional_warp_grayscale output intensity, directions, input, intensity_input
highpass_grayscale Highpass Radius, Source
histogram_scan Output Position, Contrast, Input_1
invert_grayscale Invert_Grayscale Source
crystal_1 output scale, disorder

故障排除

网桥无法连接到SD：

  • 在启动AI客户端之前，确保SD正在运行并已完全加载
  • 检查SD日志： %LOCALAPPDATA%\Adobe\Adobe Substance 3D Designer\log.txt （寻找 [SD-MCP])
  • 验证插件是否正确 sduserplugins 目录

SD在收到命令后挂起：

  • 可能使用了错误的节点定义。重新启动SD。
  • 该插件在调用SD之前验证节点定义，但库节点需要正确 pkg:// URL。

错误端口：

  • 插件正在监听 9881 默认情况下。桥梁必须使用 --port 9881.

插件未加载：

  • 删除 __pycache__/ 在插件目录中，然后重新启动SD。

许可证

MIT许可证——见 许可证

作者

建造于 马修 / ZenRay --Substance Designer的第一个MCP集成。

基于专业Substance Designer节点图模式深入分析的Pro配方架构：clouds_2→ slope_blur→ 边缘检测→ 洪水泛滥→ 多向扭曲→ 定向曲链。

贡献

PR欢迎。需要改进的关键领域：

  • 更多材料配方
  • 彩色图形支持（当前以高度/灰度为重点）
  • 插件安装的Windows+macOS路径处理
  • SD插件的自动安装脚本

相关 MCP