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

Substance Designer version	Status
16.0.3	Fully tested on a real installation
Other released 16.x versions	Expected compatible, not individually tested
Future versions	Not yet testable; capability detection is used to reduce upgrade breakage

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.

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

Tool	Access	Risk boundary
sd_ping	Read	Reports offline state without crashing
sd_get_application_info	Read	Runtime-probed information only
sd_get_capabilities	Read	Separates availability from verification
sd_list_packages	Read	Open packages only
sd_get_active_graph	Read	Current graph only
sd_list_graph_nodes	Read	Bounded pagination
sd_get_selection	Read	Bounded current selection
sd_get_node	Read	Structured current-session reference
sd_list_node_properties	Read	Runtime IDs and types
sd_search_library	Read	Loaded resources, no UI scraping
sd_create_node	Write	Verified runtime definition only
sd_create_instance_node	Write	Search-result resource reference only
sd_move_nodes	Write	Explicit nodes and finite coordinates
sd_delete_nodes	Destructive	Requires confirm: true; empty list rejected
sd_connect_nodes	Write	Explicit runtime properties; no port guessing
sd_disconnect_nodes	Write	Explicit existing connection
sd_set_node_parameter	Write	Runtime type checked; simple types only
sd_save_package	Destructive	Requires confirm: true; no Save As

Configuration

Environment variable	Default
SUBSTANCE_DESIGNER_MCP_SESSION_PATH	~/.substance-designer-mcp/session.json
SUBSTANCE_DESIGNER_MCP_PLUGIN_LOG_PATH	~/.substance-designer-mcp/logs/plugin.log
SUBSTANCE_DESIGNER_MCP_CONNECT_TIMEOUT	5 seconds
SUBSTANCE_DESIGNER_MCP_READ_TIMEOUT	5 seconds
SUBSTANCE_DESIGNER_MCP_WRITE_TIMEOUT	30 seconds
SUBSTANCE_DESIGNER_MCP_LOG_LEVEL	INFO

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.