Substance Painter MCP

An MCP server that lets AI clients inspect, audit, edit, and export from a local Adobe Substance 3D Painter project.

Version 1.0.0 provides 79 focused MCP tools. It completes the guarded resource workflow with shelf discovery, persistent shelf imports, and event-driven shelf refresh jobs, on top of the planned project lifecycle, production baking, and transactional layer authoring added throughout the 0.x releases. It is live-validated against Substance 3D Painter 12.1.1.

This is an independent community project and is not affiliated with or endorsed by Adobe.

Highlights

• Inspect the open project, Texture Sets, channels, resources, export presets, and complete layer tree.
• Create and edit Fill, Paint, and Group layers through stable layer UIDs.
• Build nested layer recipes atomically and roll back every created node if a step fails.
• Plan recipe scope and channel resolution without mutation, optionally creating an approved .spp backup before execution.
• Set OpenPBR-aware Fill channels, masks, visibility, opacity, blend modes, names, and selection.
• Control Mesh or UDIM geometry masks and compare detailed layer snapshots by UID.
• Insert Fill, Paint, Generator, Filter, Levels, Anchor, and Smart Mask effects into mask stacks.
• Apply shelf Smart Materials/Masks and configure UV or Triplanar Fill transforms.
• Assign shelf resources to individual Fill channels or complete materials.
• Import safe visual resources from approved roots into the project, current Painter session, or a writable shelf.
• Discover configured shelves and monitor explicit shelf-index refreshes through persistent event-backed jobs.
• Inspect and edit typed procedural Substance parameters, including colors and enum labels.
• Inspect, connect, reset, and transactionally restore procedural image inputs on Fill, Generator, and Filter sources.
• Discover Anchor Points with owner context and connect them to Fill channels or materials.
• Configure Planar, Spherical, and Cylindrical projection transforms and culling.
• Inspect and transactionally configure common baking properties, individual bakers, UV tiles, and linked Texture Set impact.
• Assign high-poly and cage meshes only from approved roots, then capture or apply portable baking presets.
• Preflight and batch-bake multiple Texture Sets with optional backup, cancellation, state restoration, and per-map verification.
• Preflight and monitor mesh reloads while preserving strokes and reporting Texture Set changes.
• Audit project structure and search layers or resources without mutating the project.
• Preview exact export paths before writing and restrict exports to explicitly allowed directories.
• Save verified project copies without changing the current project's location.
• Plan and create projects from approved meshes with optional templates, mesh maps, Auto UV, USD/glTF settings, verified backup, and failure recovery.
• Open approved projects safely and explicitly save the current project with post-write verification.
• Detect runtime capabilities instead of trusting Painter's reported Python API version alone.
• Keep arbitrary Python execution disabled unless the user explicitly opts in.

Compatibility

Painter builds may expose newer features while reporting an older API version string. get_capabilities therefore probes the running application for supported channels, blend modes, OpenPBR behavior, and version-specific features.

Available tools

Inspection and diagnostics

Layer editing

Layer names are not unique in Painter. All mutation tools therefore use the UIDs returned by list_layers or find_layers.

Export and advanced access