Substance-3D-Designer-MCP

中文 | English

An independent, security-focused Model Context Protocol server for Adobe Substance 3D Designer. Version 1.1.0 adds generic authoring tools while keeping the MCP runtime outside Designer so each Python environment remains isolated.

Compatibility status: Substance 3D Designer 16.0.3 is the supported baseline. The 1.0.0 capability set is real-machine verified on that version. Authoring extensions introduced in 1.1.0 are not yet real-machine verified.

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.

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.

• Creates new packages and compositing graphs without relying on the current selection.

• Reads runtime node definitions and versioned graph snapshots with explicit connections.

• Creates Output nodes with real Designer usage metadata instead of response-only labels.

• Dry-runs and applies bounded additive graph patches with runtime validation and rollback.

• Imports local bitmap resources, performs confirmed Save As, and publishes saved packages to SBSAR through the documented in-process API.

It does not generate material recipes, scrape Qt UI, expose Python or shell execution, 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": []
    }
  }
}

The MCP host starts the installed substance-designer-mcp stdio command. The Designer plugin must also be installed locally before the server can connect to Designer.

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.