Connect an AI assistant (MCP)

Pixel Painter can open a small door for AI assistants that speak the Model Context Protocol (MCP), such as Claude or Cursor. Through it the assistant can read your project, layers, brush and log, take screenshots of the viewports and, when you allow it, import meshes, fill layers with materials, paint, bake and export.

Three things take part: Pixel Painter, your assistant app, and a small free connector that sits between the two - pixelpainter-mcp on GitHub (MIT licence). Its README is the full reference: every tool, the port settings and more fixes for problems.

You set it up once. The steps below are for Windows with Claude Desktop or Claude Code.

1. Install Python

The connector is a Python program, so you need Python 3.10 or newer.

1. Download Python from python.org and run the installer.

2. On the first screen, tick Add python.exe to PATH, then click Install Now.

3. Open Command Prompt (press the Windows key, type cmd, press Enter) and check it worked:

   py --version

   You should see Python 3.10 or newer.

2. Get the connector

1. Open pixelpainter-mcp on GitHub, click the green Code button and choose Download ZIP. (If you use Git, git clone https://github.com/pixelpainterstudio/pixelpainter-mcp does the same.)

2. Unzip it somewhere it can stay, for example C:\Tools\pixelpainter-mcp. Inside you should see a folder called mcp_server with server.py in it.

3. In Command Prompt, install the one package it needs:

   py -m pip install "mcp>=1.2.0"

4. Find the full path of your Python - you need it in step 4:

   py -c "import sys; print(sys.executable)"

   It prints something like C:\Users\you\AppData\Local\Programs\Python\Python312\python.exe. Copy it.

3. Turn the bridge on in Pixel Painter

The bridge is off every time Pixel Painter starts. You ask for it with a launch option in Steam:

1. In Steam, go to Library, right-click Pixel Painter and choose Properties.
2. On the General page, type one of these into Launch Options:
   • --mcp - the assistant can only look (read the project, take screenshots).
   • --mcp-writes - it can also change your project (paint, fill, bake, export).
3. Start Pixel Painter from Steam as usual.

The option has to be in Steam: a desktop shortcut or a .bat file loses it, because Steam restarts the app. Steam keeps the option for every launch until you clear the box again.

4. Add the connector to your assistant

You need two paths from step 2: your python.exe, and server.py inside the connector folder.

Claude Desktop

1. In Claude Desktop, open Settings > Developer and click Edit Config. This opens claude_desktop_config.json.

2. Put this in it, with your own two paths. In this file every \ is written twice:

   {
     "mcpServers": {
       "pixelpainter": {
         "command": "C:\\Users\\you\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
         "args": ["C:\\Tools\\pixelpainter-mcp\\mcp_server\\server.py"]
       }
     }
   }

   If the file already has an mcpServers section, add the "pixelpainter" entry inside it instead of making a second one.

3. Save the file and restart Claude Desktop completely.

Claude Code

Run this once in a terminal, with your own two paths:

claude mcp add pixelpainter -- "C:\Users\you\AppData\Local\Programs\Python\Python312\python.exe" "C:\Tools\pixelpainter-mcp\mcp_server\server.py"

Other apps

Cursor, VS Code and other MCP clients ask for the same two things: the command (your python.exe) and one argument (the path to server.py).

5. Try it

With Pixel Painter open, ask your assistant:

• “What’s my current Pixel Painter project state?”
• “List the layers in the active texture set.”
• “Show me the 3D viewport.”

If it answers with your project, you are connected.

AI Paint skill (coming soon)

We are preparing a skill that teaches Claude to texture the way our artist does: a layer group per material, shadow and light from the baked maps, a muted pixel-art palette, and matching a reference picture you attach. It will come with the connector on GitHub, and this page will say how to add it.

If it does not work

• “cannot reach PixelPainter” - Pixel Painter is not running, or was not started with --mcp / --mcp-writes. Check the box in Steam’s Launch Options and start the app from Steam.
• “writes are disabled” - the app was started with --mcp, not --mcp-writes, or the bridge was set to read only in Edit > Settings > Integrations.
• The assistant does not list Pixel Painter at all - check both paths in your config, that every \ is doubled in the JSON file, and restart the assistant app.
• “No module named mcp” - the package went into a different Python. Run step 2.3 again with the same python.exe your config names: "C:\...\python.exe" -m pip install "mcp>=1.2.0".

Good to know

• The bridge is off unless you start Pixel Painter with one of the options. Clear the box in Steam when you are done.
• It only accepts connections from your own computer, and every request must carry a token that Pixel Painter makes fresh each session. You do not need to set anything up for that.
• While it runs, Edit > Settings > Integrations lets you drop it to read only or turn it off for the rest of the session.
• Everything the assistant does is written to the log, so you can see what it read and changed.
• Most of what the assistant paints or fills is one Ctrl+Z step, but not everything can be undone: changing the resolution resamples every texture, and importing a mesh starts a new project. Save a copy of your work before you let it make big changes.