ArmorPaint MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ArmorPaint MCP Load the dragon model and paint a fire texture on its scales."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ArmorPaint MCP
A local MCP server for controlling ArmorPaint from Codex, Claude, Cursor, or another agent that supports stdio MCP. It exposes 41 tools for projects, meshes, materials, nodes, layers, masks, painting, baking, cameras, and exports. Viewport captures are returned as images.
The server needs the native ArmorPaint bridge included here. An unmodified ArmorPaint app cannot connect. The Apple silicon build is tested; native Windows and Linux builds remain unverified. Claude and Cursor client instructions are provided, but those clients have not been tested directly.
Install
Use Python 3.11 or newer. From this folder:
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/armorpaint-mcp --helpUse the full path to .venv/bin/armorpaint-mcp in your client settings. On Windows, the executable is .venv\Scripts\armorpaint-mcp.exe.
The MCP server needs no API key. Your agent supplies the model, reasoning, and image interpretation.
Related MCP server: dcc-mcp-substance3d-painter
Build the ArmorPaint bridge
Skip this step if your app already includes this bridge. For Apple silicon, install full Xcode with its Metal toolchain, then run:
git clone https://github.com/armory3d/armorpaint.git ../armorpaint
git -C ../armorpaint checkout 906418acc600132fa927876d208eb452dc5a0967
.venv/bin/python scripts/build_macos.py ../armorpaint --output build/macosCopy build/macos/Build/Products/Release/ArmorPaint.app to /Applications/ArmorPaint MCP.app, or use its existing location in your settings. This is a local ad hoc signed build, without Apple notarization.
The bridge is pinned to ArmorPaint 1.1alpha at the revision above. For other desktop platforms, apply it with scripts/apply_bridge.py and follow the upstream build instructions.
Choose your paths
Replace the example paths below with absolute paths. Keep spaces inside the quotes. Do not leave ~, $HOME, or placeholders in JSON or TOML.
Option | Purpose |
| Bridge-enabled ArmorPaint app or executable |
| Private connection and preferences folder, created automatically |
| Folder for meshes, references, projects, and exports |
| Start ArmorPaint when a client connects |
| Server operation timeout in seconds |
Create your workspace folder first. Use the same bridge directory in different clients to share a session. Use different directories for independent sessions.
Claude Desktop
Open Settings → Developer → Edit Config. On macOS, the file is ~/Library/Application Support/Claude/claude_desktop_config.json.
Merge this entry into your configuration, preserving other servers. The same template is in setup/mcp.json.
{
"mcpServers": {
"armorpaint": {
"command": "/absolute/path/armorpaint-mcp/.venv/bin/armorpaint-mcp",
"args": [
"--launch",
"--app", "/Applications/ArmorPaint MCP.app",
"--bridge-dir", "/absolute/path/armorpaint-session",
"--workspace", "/absolute/path/texture-projects",
"--timeout", "180"
]
}
}
}Quit and reopen Claude Desktop, then check for armorpaint in its connectors. These settings apply to the desktop app, not a remote connector in the Claude website. Official setup guide.
Claude Code
Replace the paths and run:
claude mcp add --transport stdio --scope user armorpaint -- \
"/absolute/path/armorpaint-mcp/.venv/bin/armorpaint-mcp" \
--launch \
--app "/Applications/ArmorPaint MCP.app" \
--bridge-dir "/absolute/path/armorpaint-session" \
--workspace "/absolute/path/texture-projects" \
--timeout 180Use --scope local instead for a connection specific to the current project. To inspect the entry and allow time for startup and baking:
claude mcp get armorpaint
MCP_TIMEOUT=90000 MCP_TOOL_TIMEOUT=200000 claudeThe Claude timeout variables use milliseconds. Run /mcp inside Claude Code to check the connection. Official documentation.
Cursor
Merge the JSON example above into ~/.cursor/mcp.json for all projects, or .cursor/mcp.json inside one project. For Cursor, add "type": "stdio" inside the armorpaint entry. Replace the paths, reload Cursor, and enable armorpaint in its MCP settings. Start from setup/mcp.json. Official documentation.
Codex
Add this to ~/.codex/config.toml, replacing the paths. Update the existing table if armorpaint is already configured. A copy is in setup/codex.toml.
[mcp_servers.armorpaint]
command = "/absolute/path/armorpaint-mcp/.venv/bin/armorpaint-mcp"
args = [
"--launch",
"--app", "/Applications/ArmorPaint MCP.app",
"--bridge-dir", "/absolute/path/armorpaint-session",
"--workspace", "/absolute/path/texture-projects",
"--timeout", "180"
]
startup_timeout_sec = 90
tool_timeout_sec = 200The desktop app and CLI share MCP settings on the same host. Restart the MCP connection in Codex settings, or restart the app. In the CLI, use /mcp in a fresh session. codex mcp get armorpaint shows the saved configuration. Official documentation.
Other agents
Configure a local stdio MCP server using the same executable and arguments. Image inspection requires support for MCP image content. A remote-only agent needs a local runtime to launch this server and ArmorPaint.
The MCP tools use standard schemas; they are not tied to a model provider. Compatibility has been checked with the official MCP SDK and Codex's runtime, not every agent application.
First use
Ask your agent:
Use ArmorPaint to check the connection and inspect the current scene. Report its objects, layers, and texture resolution without changing anything.
It should call armorpaint_status and armorpaint_get_state. Use armorpaint_list_node_types before editing material graphs. The armorpaint://project resource also returns the scene state.
Put your mesh and reference in the workspace, attach the reference image to the conversation, and describe the finish you want. Ask the agent to save a checkpoint, inspect viewport captures, and export the project and PBR maps.
Session behavior
The app polls a private local mailbox on its main thread. Requests are serialized across clients. No network listener is created. Preferences and armorpaint.log are stored inside the bridge directory. Closing the client leaves ArmorPaint open.
--workspace checks file paths accepted by the normal tools. It is not an operating-system sandbox: the app runs as your user, and imported projects may reference other assets. Scripting is disabled by default. --allow-scripts adds armorpaint_run_script; it also requires the app to start with ARMORPAINT_MCP_ALLOW_SCRIPTS=1, which the launch option sets when scripting is enabled.
Save checkpoints before substantial edits. A timed-out operation may already have changed the scene, and undo does not cover every operation. Inspect the result before retrying.
Troubleshooting
Server missing: check JSON or TOML syntax, absolute executable paths, and client reload status.
Not connected: confirm the app includes the bridge, keep
--launch, and use the same bridge directory in both processes.App startup failed: inspect
armorpaint.login the bridge directory. A graphical desktop is required.Path rejected: keep input and output files inside the configured workspace.
Operation timed out: inspect the scene and logs, then adjust both the client and server timeouts if needed.
Unexpected texture: inspect exported maps, UVs, object masks, and lighting. The agent must judge the visual result.
License
The MCP integration is MIT licensed. ArmorPaint and its dependencies retain their own licenses. This project is independent of Armory3D and the agent vendors.
Available Tools
41 toolsarmorpaint_add_nodeB
Add a material node using a type returned by list_node_types. Returns the graph including the new node ID.
Inputs: type (required), x, y, material_id. Returns: object
armorpaint_bakeA
Bake a mesh map to PNG using ArmorPaint. Types: 0=curvature, 1=tangent normal, 2=object normal, 3=height, 4=derivative, 5=position, 6=UV, 7=material ID, 8=object ID, 9=vertex color, 10=AO, 11=lightmap, 12=bent normal, 13=thickness. Types 1/3/4 require a high-poly object index; 10–13 require ray tracing. Use a regular paint layer. Import the exported image for persistent reuse.
Inputs: path_name (required), type, offset, radius, +7 more. Returns: object
armorpaint_capture_viewportARead-onlyIdempotent
Capture the rendered 3D viewport as a PNG and return it as an MCP image for visual inspection.
Inputs: no named parameters.
armorpaint_clear_layerBDestructive
Replace a paint layer's pixels with uniform color and packed PBR values. RGBA components range from zero to one.
Inputs: layer_id (required), color, metallic, occlusion, +1 more. Returns: object
armorpaint_connect_nodesB
Connect an output socket to an input socket, replacing any previous connection to that input.
Inputs: to_node (required), from_node (required), to_socket (required), from_socket (required), +1 more. Returns: object
armorpaint_create_layerA
Create a paint layer, material fill, mask, or group. Masks require a parent layer ID. UV modes: 0=UV map, 1=triplanar, 2=projection.
Inputs: name (required), kind, white, uv_type, +2 more. Returns: object
armorpaint_create_materialA
Create and select a named PBR material.
Inputs: name (required). Returns: object
armorpaint_delete_materialADestructive
Delete a material. The final material cannot be deleted.
Inputs: material_id (required). Returns: object
armorpaint_disconnect_nodesB
Disconnect the incoming link to a material node input socket.
Inputs: socket (required), node_id (required), material_id. Returns: object
armorpaint_export_layerARead-onlyIdempotent
Export one layer's base color/mask, normal, or packed occlusion-roughness-metallic texture to a PNG file.
Inputs: path_name (required), channel, layer_id, overwrite. Returns: object
armorpaint_export_materialCRead-onlyIdempotent
Export a material as an ArmorPaint material file.
Inputs: path_name (required), overwrite, material_id. Returns: object
armorpaint_export_meshBRead-onlyIdempotent
Export the current mesh to an OBJ file.
Inputs: path_name (required), overwrite. Returns: object
armorpaint_export_texturesA
Export the visible layer stack as PNG PBR maps using an installed preset. Get exact preset names from list_node_types.
Inputs: directory (required), name, preset, overwrite. Returns: object
armorpaint_fill_layerC
Paint the selected material over an entire paint layer, respecting object masks.
Inputs: layer_id, material_id. Returns: object
armorpaint_get_material_graphARead-onlyIdempotent
Read a material's nodes, socket values, buttons, and connections. material_id=-1 uses the current material.
Inputs: material_id. Returns: object
armorpaint_get_stateARead-onlyIdempotent
Inspect objects, triangle counts, materials, layers, assets, current selection, and project path.
Inputs: no named parameters. Returns: object
armorpaint_import_maskA
Import a grayscale image as a mask for a paint or fill layer. White reveals the layer; black hides it.
Inputs: parent_id (required), path_name (required). Returns: object
armorpaint_import_materialB
Import an ArmorPaint .arm material library into the current project.
Inputs: path_name (required). Returns: object
armorpaint_import_meshADestructive
Import a UV-mapped OBJ or supported Blender mesh. Replacement can clear the current layers; use append mode to preserve geometry.
Inputs: path_name (required), replace, clear_layers, discard_changes. Returns: object
armorpaint_import_textureA
Import an image into the project's texture assets. Returns the updated asset list.
Inputs: path_name (required). Returns: object
armorpaint_layer_actionBDestructive
Duplicate, delete, merge, reorder, or convert a layer; apply or invert masks. Save a checkpoint before merging or deleting.
Inputs: action (required), layer_id (required), index. Returns: object
armorpaint_list_node_typesARead-onlyIdempotent
List material node types with socket and button schemas, and installed export presets. Query this before building node graphs.
Inputs: no named parameters. Returns: object
armorpaint_new_projectADestructive
Create a new project. Save the current project before discarding it.
Inputs: discard_changes. Returns: object
armorpaint_open_projectADestructive
Open an existing .arm project. Save the current project first.
Inputs: path_name (required), discard_changes. Returns: object
armorpaint_paint_strokeA
Paint one continuous stroke. Screen points use normalized viewport coordinates; world points use XYZ and are projected through the current camera. Hidden surfaces require another camera view.
Inputs: points (required), text, tool, space, +5 more. Returns: object
armorpaint_redoA
Redo the most recently undone operation.
Inputs: no named parameters. Returns: object
armorpaint_remove_nodeADestructive
Remove a material node and its links. The PBR output node is protected.
Inputs: node_id (required), material_id. Returns: object
armorpaint_save_projectA
Save the project to an absolute .arm path, optionally packing imported assets. Existing files require overwrite=true.
Inputs: path_name (required), overwrite, pack_assets. Returns: object
armorpaint_select_layerC
Select a layer by stable ID.
Inputs: layer_id (required). Returns: object
armorpaint_select_materialB
Select a material by its stable ID.
Inputs: material_id (required). Returns: object
armorpaint_select_objectA
Select a mesh by the zero-based index returned by get_state.
Inputs: index (required). Returns: object
armorpaint_set_cameraB
Orbit the camera by yaw/pitch radians, move forward by zoom units, or reset its view. projection: 0=perspective, 1=orthographic.
Inputs: fov, yaw, zoom, pitch, +2 more. Returns: object
armorpaint_set_layerC
Edit a layer. object_mask=0 affects all objects; index+1 restricts it to one object. Opacity ranges from zero to one.
Inputs: layer_id (required), name, angle, blend, +5 more. Returns: object
armorpaint_set_layer_channelsC
Enable or disable individual PBR channels on a paint or fill layer.
Inputs: layer_id (required), height, normal, opacity, +4 more. Returns: object
armorpaint_set_material_pbrA
Set constant PBR channel values, disconnecting existing links to those channels. Color uses RGBA values in the ArmorPaint material UI.
Inputs: color, height, opacity, emission, +5 more. Returns: object
armorpaint_set_node_valueB
Set a node input, output, or button value. The numeric array must have the length reported by get_material_graph.
Inputs: kind (required), index (required), values (required), node_id (required), +1 more. Returns: object
armorpaint_set_objectB
Rename or show/hide a mesh object.
Inputs: index (required), name, visible. Returns: object
armorpaint_set_resolutionA
Resize the project's texture maps. Larger maps increase GPU memory use.
Inputs: resolution (required). Returns: object
armorpaint_set_viewportA
Set viewport channel: 0=lit, 1=base color, 2=normal, 3=AO, 4=roughness, 5=metallic, 6=opacity, 7=height, 8=emission, 10=UV, 14=mask, 15=path traced.
Inputs: mode, wireframe, environment, environment_angle, +1 more. Returns: object
armorpaint_statusARead-onlyIdempotent
Check the local connection and supported bridge version without changing the project.
Inputs: no named parameters. Returns: object
armorpaint_undoA
Undo the most recent operation recorded by ArmorPaint history. Not every operation is covered; checkpoints protect whole workflows.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 41 tools
Most tools target a distinct resource-action pair, and the detailed descriptions help separate overlapping operations like set_layer vs layer_action and fill_layer vs paint_stroke. A few close neighbors exist—export_layer vs export_textures and set_node_value vs set_material_pbr—but they are still distinguishable from their names and descriptions.
The armorpaint_ prefix plus verb_noun pattern is consistent overall, e.g. create_material, delete_material, connect_nodes, export_mesh. Minor deviations exist such as new_project instead of create_project, bake as a bare verb, and layer_action as a generic suffix, but the naming is still predictable and readable.
With 41 tools, this exceeds the 25-tool threshold that typically indicates an overgrown surface. The tools are organized by subsystem and each has a real purpose, but the count is heavy enough that an agent must manage a large selection set.
The tool set covers the full ArmorPaint workflow: project handling, mesh/material/node graph editing, layer management, painting, baking, viewport inspection, and multiple export paths. Minor gaps exist—such as no object deletion or duplicate, and no explicit material rename—but they are workaroundable and do not block core workflows.
Related MCP Connectors
Generate 3D models, worlds, PBR materials, and coordinated asset packs from AI agents.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Generate and edit images, video, voice, lip-sync and 3D models from your AI agent.
Make and edit images, videos, 3D models and documents with awen's creative agent.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables control of Open Brush 3D painting software through natural language commands, allowing LLMs to create drawings, manipulate brushes, import 3D models, manage colors, layers, and camera settings via the Open Brush HTTP API.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to control Substance 3D Painter, inspecting projects and exporting texture sets via a secure preset-based tool.65 PyPI1MIT
- AlicenseAqualityDmaintenanceEnables AI-driven 3D modeling in Blender by providing tools to create primitives, apply modifiers and materials, set up lighting and cameras, capture viewport snapshots, export assets, inspect scenes, and execute Python commands via natural language.10MIT
- AlicenseAqualityBmaintenanceEnables an AI assistant to inspect and edit a live Krita 6 desktop session, create and modify documents and layers, paint with native brushes, and receive inline PNG previews.561MIT