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工具

材料配方

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）

______________________________________________________________________

故障排除

网桥无法连接到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许可证——见 许可证

______________________________________________________________________

作者

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

______________________________________________________________________

贡献

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

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