substance-designer-mcp

An independent, security-focused Model Context Protocol server for Adobe Substance 3D Designer. Version 1.0.0 is real-machine verified on Designer 16.0.3 and keeps the MCP runtime outside Designer so each Python environment remains isolated.

Verification status: Designer 16.0.3 completed the protected 33/33 real-machine E2E suite, including the MCP bridge, Graph and selection reads, Atomic and Library node creation, movement, connection and disconnection, simple parameter editing, destructive confirmation, package save, session cleanup, and restart behavior. Offline unit, contract, and TCP integration tests use a strict fake API and are not presented as real-machine evidence. See the Designer 16.0.3 test record.

Chinese documentation: README.zh-CN.md

Compatibility

A version is marked as fully tested only after the plugin and MCP tools have been exercised in a real Substance Designer installation. Capability detection does not replace real-version testing.

Related MCP server: comfyui-mcp-secure

What it does

• Reads application, package, graph, selection, node, property, and capability state.

• Searches resources in packages already loaded by Designer.

• Creates verified atomic nodes and instances of resources returned by the search tool.

• Moves and deletes explicit nodes, connects explicit runtime properties, and writes supported simple parameters.

• Saves one already-saved package in place after explicit confirmation.

It does not generate material recipes, scrape Qt UI, expose Python or shell execution, depend on NodeStation, access the internet, upload telemetry, or provide remote control.

Architecture

MCP host
   | stdio
External Python 3.10+ MCP server
   | authenticated length-prefixed JSON on 127.0.0.1
Designer Python plugin
   | allow-listed command registry and Qt main-thread dispatcher
Focused services and compatibility probes
   | verified Adobe Python API calls
Substance 3D Designer (real-machine verified: 16.0.3)

The external process never imports Adobe's sd module. The bridge contains transport only. Designer API calls live in plugin services or the compatibility adapter. See architecture.md and security-model.md.

Installation

External MCP server

Windows PowerShell:

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

Cross-platform:

python3 -m venv .venv
.venv/bin/python -m pip install -e .

The installed command is substance-designer-mcp and uses stdio by default.

Designer plugin

Build the distributable ZIP:

.\.venv\Scripts\python.exe scripts\build_plugin.py

Install into an explicit user plugin directory:

.\.venv\Scripts\python.exe scripts\install_plugin.py --target "C:\path\to\Designer\user-plugins"

The installer refuses Adobe's application installation tree and backs up an existing plugin. Manual Plugin Manager loading and uninstall details are in installation.md.

MCP host configuration

{
  "mcpServers": {
    "substance-designer": {
      "command": "substance-designer-mcp",
      "args": []
    }
  }
}

This is generic stdio configuration and is not tied to one AI client.

Tools

Configuration

Set the session and plugin-log path variables before Designer imports the plugin. This lets an isolated test session avoid replacing the normal per-user state files.

Logs use stderr or rotating files. Stdio stdout is reserved for MCP protocol messages.

Development

.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\ruff.exe check .
.\.venv\Scripts\ruff.exe format --check .
.\.venv\Scripts\mypy.exe src
.\.venv\Scripts\python.exe -m build
.\.venv\Scripts\python.exe scripts\build_plugin.py

API claims must come from Designer's bundled Python API documentation. Contribution and release rules are in CONTRIBUTING.md and development.md.

License and trademarks

MIT. Adobe and Substance 3D Designer are trademarks of Adobe. This project is independent and is not endorsed by Adobe.