substance-designer-mcp

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

Verification status: The original 1.0.0 tool set completed the protected 33/33 real-machine E2E suite on Designer 16.0.3, including the bridge, reads, node editing, connections, simple parameters, confirmation, save, cleanup, and restart behavior. The 1.1.0 package/graph creation, snapshot, Output metadata, graph patch, bitmap import, Save As, and SBSAR export additions are checked against the bundled 16.0.3 API and offline-tested, but have not yet completed a fresh real-machine E2E run. Offline evidence is 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: nuke-mcp

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, 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.

Codex and PaperHub plugin metadata

The repository also ships Codex plugin metadata for public distribution:

• .codex-plugin/plugin.json provides the display name, icon, prompts, and capability summary.

• .mcp.json uses the portable stdio command substance-designer-mcp; it intentionally does not contain a developer-specific absolute path.

• assets/icon.png is the composer icon used by Codex/PaperHub surfaces.

When registering this MCP in a shared marketplace such as PaperHub, use the stdio startup command substance-designer-mcp with empty startup arguments. Each user still needs to install the Python package and the Designer plugin bridge locally before the MCP can connect to Substance 3D 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.