Skip to main content
Glama
substance-designer-mcp

substance-designer-mcp

by MikeLi-28

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

Substance Designer version

Status

16.0.3

1.0.0 baseline real-machine tested; 1.1.0 authoring additions await a fresh live run

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.

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

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

sd_create_package

Write

Creates one unsaved user package

sd_create_graph

Write

Explicit package and portable unique identifier

sd_list_node_definitions

Read

Runtime catalog; bounded and searchable

sd_get_graph_snapshot

Read

Versioned bounded nodes, properties, connections, and presets

sd_open_graph

Write

Opens one explicit graph in the editor

sd_create_graph_output

Write

Explicit identifier, label, group, and official usages

sd_validate_graph_patch

Read

Dry-run only; definitions, ports, types, targets, and cycles

sd_apply_graph_patch

Write

Additive patch only; rollback of all created nodes on failure

sd_import_bitmap

Write

Existing local bitmap and explicit embed method only

sd_save_package_as

Destructive

Absolute .sbs, existing parent, overwrite opt-in, confirmation

sd_export_package_sbsar

Destructive

Saved package, explicit settings, overwrite opt-in, confirmation

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.

Available Tools

22 tools
sd_connect_nodesC

Connect explicit runtime properties after direction, type, and duplicate checks.

Inputs: graph (required), source_node (required), target_node (required), source_property (required), +1 more. Returns: object

sd_create_graph_outputC

Create an Output node with explicit official usage metadata.

Inputs: graph (required), label (required), usages (required), position (required), +3 more. Returns: object

sd_create_instance_nodeA

Create one instance from a resource returned by sd_search_library.

Inputs: graph (required), position (required), resource (required). Returns: object

sd_create_nodeB

Create one verified atomic node at an explicit position without auto-connecting it.

Inputs: graph (required), position (required), definition_id (required). Returns: object

sd_delete_nodesA
Destructive

Delete explicit nodes from one graph only when confirm is true.

Inputs: graph (required), confirm (required), node_identifiers (required). Returns: object

sd_disconnect_nodesC

Disconnect one explicit existing property connection.

Inputs: graph (required), source_node (required), target_node (required), source_property (required), +1 more. Returns: object

sd_export_package_sbsarB
Destructive

Export one saved package to .sbsar with explicit publication settings.

Inputs: confirm (required), package (required), file_path (required), overwrite (required), +5 more. Returns: object

sd_get_active_graphA
Read-onlyIdempotent

Read the current editable graph, package, node count, and selection count.

Inputs: no named parameters. Returns: object

sd_get_application_infoA
Read-onlyIdempotent

Read Designer version, Python, platform, open packages, graph, and capabilities.

Inputs: no named parameters. Returns: object

sd_get_capabilitiesA
Read-onlyIdempotent

Read the runtime-probed capability matrix and verification status.

Inputs: no named parameters. Returns: object

sd_get_graph_snapshotA
Read-onlyIdempotent

Read a bounded versioned graph snapshot including explicit connections.

Inputs: graph (required), limit, include_values. Returns: object

sd_get_nodeA
Read-onlyIdempotent

Read one node by a structured current-session node reference.

Inputs: node (required), detail. Returns: object

sd_get_selectionB
Read-onlyIdempotent

Read the current graph node selection with a bounded result size.

Inputs: limit, detail. Returns: object

sd_list_graph_nodesB
Read-onlyIdempotent

List a bounded page of nodes from a structured graph reference.

Inputs: graph (required), limit, detail, offset. Returns: object

sd_list_node_propertiesB
Read-onlyIdempotent

List runtime input and output properties, types, values, and connection state.

Inputs: node (required). Returns: object

sd_list_packagesA
Read-onlyIdempotent

List packages currently open in Designer as structured references.

Inputs: no named parameters. Returns: object

sd_move_nodesB
Idempotent

Move one to one hundred explicitly identified nodes to finite coordinates.

Inputs: graph (required), moves (required). Returns: object

sd_open_graphC

Open one explicit graph resource in Designer's editor.

Inputs: graph (required). Returns: object

sd_pingA
Read-onlyIdempotent

Report MCP, bridge, plugin, Designer version, session, and compatibility status.

Inputs: no named parameters. Returns: object

sd_save_packageA
Destructive

Save one already-saved open package in place; never performs Save As.

Inputs: confirm (required), package (required). Returns: object

sd_set_node_parameterC
Idempotent

Set a supported simple parameter after reading and validating its runtime SD type.

Inputs: node (required), value (required), property_id (required). Returns: object

sd_validate_graph_patchA
Read-onlyIdempotent

Dry-run a versioned additive graph patch without changing Designer.

Inputs: graph (required), patch (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 22 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: connect, disconnect, delete, create, move, list, get, set, export, etc. Even similar-sounding tools like sd_create_node and sd_create_instance_node differ in that one creates an atomic node and the other creates an instance from a library resource.

    Naming Consistency5/5

    All tools follow a consistent 'sd_verb_noun' pattern using snake_case. Verbs like connect, create, delete, get, list, set are all lowercase and nouns are clearly descriptive.

    Tool Count5/5

    22 tools is a well-scoped number for a Substance Designer interaction layer. It covers graph, node, package, and utility operations without being excessive or sparse.

    Completeness5/5

    The tool set covers the full lifecycle of graph and node manipulation: creation, reading, updating (parameters, connections), deletion, and export. Also includes utilities like ping and capability checks. No obvious gaps in typical workflows.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A production-grade MCP server for Foundry Nuke that enables AI assistants to understand and manipulate compositing environments, including AOVs, deep workflows, distortion, tracking, OCIO/ACEScct, and CopyCat ML.
      45
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that lets AI assistants control Adobe Illustrator locally—running ExtendScript, capturing canvas screenshots, exporting artwork, and optionally remembering techniques—all without network activity.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Adapter that runs an MCP server inside Substance 3D Designer, enabling tools to inspect and interact with the active designer session and its packages through natural language.
      197 PyPI
      7
      MIT