Skip to main content
Glama
ArmorPaint MCP
by gprethesh

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 --help

Use 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/macos

Copy 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

--app

Bridge-enabled ArmorPaint app or executable

--bridge-dir

Private connection and preferences folder, created automatically

--workspace

Folder for meshes, references, projects, and exports

--launch

Start ArmorPaint when a client connects

--timeout

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 180

Use --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 claude

The 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 = 200

The 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.log in 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 tools
armorpaint_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_viewportA
Read-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_layerB
Destructive

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_materialA
Destructive

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_layerA
Read-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_materialC
Read-onlyIdempotent

Export a material as an ArmorPaint material file.

Inputs: path_name (required), overwrite, material_id. Returns: object

armorpaint_export_meshB
Read-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_graphA
Read-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_stateA
Read-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_meshA
Destructive

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_actionB
Destructive

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_typesA
Read-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_projectA
Destructive

Create a new project. Save the current project before discarding it.

Inputs: discard_changes. Returns: object

armorpaint_open_projectA
Destructive

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_nodeA
Destructive

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_statusA
Read-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

    B3.3/5.0

    Scored across 41 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      10
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      56
      1
      MIT