内容
# Substance Painter MCP
[](https://www.python.org/)
[](https://github.com/modelcontextprotocol/python-sdk)
[](https://www.adobe.com/products/substance3d/apps/painter.html)
[](LICENSE)
一个允许AI客户端检查、审计、编辑和导出本地Adobe Substance 3D Painter项目的MCP服务器。
版本 **0.2.0** 是对原始概念验证的重大现代化改造。它提供了22种专注的MCP工具、可安装的Python包、有限的连接超时、基于能力的兼容性、UID安全的图层编辑、受保护的纹理导出、自动测试和针对 **Substance 3D Painter 12.1.1** 的实时验证。
> 这是一个独立的社区项目，与Adobe无关或未得到Adobe的认可。
## 亮点
- 检查打开的项目、纹理集、通道、资源、导出预设和完整的图层树。
- 通过稳定的图层UID创建和编辑填充、绘制和分组图层。
- 设置OpenPBR感知的填充通道、遮罩、可见性、不透明度、混合模式、名称和选择。
- 审计项目结构并在不改变项目的情况下搜索图层或资源。
- 在写入之前预览确切的导出路径，并将导出限制在明确允许的目录中。
- 检测运行时能力而不仅仅依赖Painter报告的Python API版本。
- 除非用户明确选择启用，否则保持任意Python执行禁用。
## 兼容性
| 组件 | 支持/验证 |
|---|---|
| Adobe Substance 3D Painter | 与12.1.1版本实时测试 |
| Painter Python API | 在验证版本中运行时报告0.3.5 |
| Python | 3.10或更新版本 |
| MCP Python SDK | `mcp>=1.28,<2` |
| 传输 | MCP标准输入输出到Painter HTTP远程脚本 |
| Painter端点 | 默认`localhost:60041` |
Painter构建版本可能会在报告旧的API版本字符串的同时公开新功能。因此，`get_capabilities`会探测正在运行的应用程序以获取支持的通道、混合模式、OpenPBR行为和版本特定的功能。
## 可用工具
### 检查和诊断
| 工具 | 目的 |
|---|---|
| `painter_status` | 检查连接、Painter/API版本和项目是否打开。 |
| `get_project_info` | 返回项目路径和纹理集。 |
| `get_capabilities` | 探测通道、混合模式和版本相关的运行时功能。 |
| `audit_project` | 报告分辨率、通道、图层卫生和过时的资源。 |
| `list_layers` | 返回基于UID的递归图层树。 |
| `find_layers` | 按名称、类型或可见性搜索并包含父路径。 |
| `list_export_presets` | 列出内置和架子上导出预设。 |
| `list_project_resources` | 列出当前项目引用的资源。 |
| `search_resources` | 按查询、使用、URL或类型搜索资源。 |
### 图层编辑
| 工具 | 目的 |
|---|---|
| `create_fill_layer` | 创建一个填充图层，带有可选的基础颜色。 |
| `create_paint_layer` | 创建一个绘制图层。 |
| `create_group` | 创建一个图层组。 |
| `set_fill_base_color` | 将sRGB输入颜色转换为Painter的工作颜色空间。 |
| `set_fill_channels` | 设置多个统一通道，包括粗糙度、金属度和发射别名。 |
| `set_layer_mask` | 添加、替换或删除白色/黑色遮罩。 |
| `set_layer_properties` | 设置可见性和通道特定的不透明度或混合模式。 |
| `rename_layer` | 按UID重命名图层。 |
| `select_layers` | 按UID选择一个或多个图层。 |
| `delete_layer` | 按UID删除图层。 |
图层名称在Painter中不是唯一的。因此，所有变异工具都使用`list_layers`或`find_layers`返回的UID。
### 导出和高级访问
| 工具 | 目的 |
|---|---|
| `plan_texture_export` | 在不写入任何内容的情况下解析预期的输出文件和冲突。 |
| `export_textures` | 在批准的根目录中导出并验证每个生成的文件和大小。 |
| `execute_python` | 仅在明确启用时运行任意Painter Python。 |
## 安装
```powershell
git clone https://github.com/elliezu/SubstancePainterMCP.git
cd SubstancePainterMCP
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .
```
用于开发和测试：
```powershell
.venv\Scripts\python.exe -m pip install -e ".[dev]"
.venv\Scripts\python.exe -m pytest
```
## 启动带有远程脚本的Painter
Painter必须作为新进程启动，并启用远程脚本：
```powershell
"C:\Program Files\Adobe\Adobe Substance 3D Painter\Adobe Substance 3D Painter.exe" --enable-remote-scripting
```
您可以将相同的参数添加到Windows快捷方式的 **目标** 字段：
```text
"C:\Program Files\Adobe\Adobe Substance 3D Painter\Adobe Substance 3D Painter.exe" --enable-remote-scripting
```
如果Painter已经在没有此参数的情况下运行，则启动快捷方式可能只会聚焦现有的进程。完全退出Painter，然后从修改后的快捷方式重新启动。不需要手动配置端口：Painter会自动打开 `localhost:60041`。
在PowerShell中验证监听器：
```powershell
Get-NetTCPConnection -LocalPort 60041
```
## 配置MCP客户端
Windows上Claude Desktop的示例：
```json
{
"mcpServers": {
"substance-painter": {
"command": "C:\\Tools\\SubstancePainterMCP\\.venv\\Scripts\\python.exe",
"args": ["-m", "substance_painter_mcp"],
"env": {
"SP_MCP_TIMEOUT": "120",
"SP_MCP_EXPORT_ROOTS": "D:\\SubstanceExports"
}
}
}
}
```
替换路径为您的安装和导出目录。您也可以直接使用 `.venv\Scripts\substance-painter-mcp.exe` 作为命令。
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---:|---|
| `SP_MCP_HOST` | `localhost` | Painter远程脚本主机。 |
| `SP_MCP_PORT` | `60041` | Painter远程脚本端口。 |
| `SP_MCP_TIMEOUT` | `30` | 秒为单位的HTTP超时。 |
| `SP_MCP_ALLOW_EXECUTE_PYTHON` | 未设置 | 设置为 `1` 以公开任意Python执行。 |
| `SP_MCP_EXPORT_ROOTS` | 未设置 | 批准的导出根目录。用`;`分隔多个Windows路径。 |
在配置 `SP_MCP_EXPORT_ROOTS` 之前，导出是禁用的。 `plan_texture_export` 执行只读预检。 `export_textures` 重复验证并拒绝现有目标，除非明确提供 `overwrite=true`。
## 安全模型
- 用户值（如名称、颜色和UID）序列化为base64编码的JSON，而不是插入Python源代码。
- 结果直接返回；服务器不再依赖共享的 `C:\temp` 结果文件，该文件可能过时或在请求之间冲突。
- 失败的连接在配置的超时时间后停止，而不是挂起一小时。
- 连接、HTTP和Painter脚本失败报告为不同的错误类型。
- 图层变异使用UID以避免在名称重复时编辑错误的图层。
- 纹理导出需要批准的根目录、预检计划、明确的覆盖许可和导出后文件验证。
- 任意Python代码是可选的，默认禁用。
服务器设计用于本地使用。不要将Painter的远程脚本端口暴露给不受信任的网络。
## 测试和实时验证
运行自动化套件：
```powershell
.venv\Scripts\python.exe -m pytest
```
当前套件涵盖请求编码、类型错误、超时行为、输入隔离、颜色转换、不透明度验证和操作级行为。
在Painter运行并打开一个 disposable 项目时，使用实时烟雾测试：
```powershell
# 只读检查
.venv\Scripts\python.exe scripts\live_smoke.py
# 可逆创建 -> 编辑 -> 验证 -> 删除循环
.venv\Scripts\python.exe scripts\live_smoke.py --write
```
0.2.0验证运行使用了Painter 12.1.1和一个示例项目。它验证了所有22个MCP工具的注册，然后实时测试了连接和项目检查、可逆的组/填充/绘制创建、OpenPBR通道别名、白色/黑色遮罩、不透明度和混合模式、多图层选择、项目审计、一个包含1845个资源的架子搜索、预设发现和带有输出文件验证的256像素PNG纹理导出。在验证后删除了临时图层和导出工件。
## 路线图和发行说明
- 查看 [CHANGELOG.md](CHANGELOG.md) 获取详细的0.2.0现代化改造笔记。
- 查看 [docs/ROADMAP.md](docs/ROADMAP.md) 获取计划的图层配方、快照、备份、引擎特定的导出配置文件、异步烘焙和Blender往返工作流。
## 许可证
MIT。查看 [LICENSE](LICENSE)。
