NeuroPaint-X

An MCP server that gives an AI an Ibis-Paint-level image editor — a layered raster painting canvas it drives with tool calls, renders, looks at, and iterates on. (Python package name: mcp_paint.)

• Stateful documents held in server memory: layers, blend modes, opacity, alpha-lock, undo/redo.

• skia-python rendering: anti-aliased brushes (soft/hard/ink/marker/airbrush/ pencil), shapes, linear/radial gradients, flood fill, text, filters (blur / drop-shadow / glow / grayscale / saturate / brightness / contrast / invert / sharpen).

• Pulls images and fonts straight from the internet — place_image(url=…), draw_text(google_font="Poppins") or font_url=….

• Token-frugal by design (see below).

Keeping token cost low

Image tokens ≈ width*height / 750. NeuroPaint-X minimises them:

Each render reply also reports approx_image_tokens so the model can self-budget.

Related MCP server: ImageMcp

Run it

python -m venv .venv && . .venv/bin/activate
pip install -e .

# HTTP (for a Claude connector) — default 127.0.0.1:8765
python -m mcp_paint

# or stdio (for local Claude Code / Desktop)
MCP_PAINT_TRANSPORT=stdio python -m mcp_paint

Environment

Use as a Claude connector (self-hosted)

1. Run it on your box, bound to localhost, with a token:

   MCP_PAINT_TOKEN=$(openssl rand -hex 24) python -m mcp_paint

2. Expose that port over HTTPS with a tunnel:

   cloudflared tunnel --url http://localhost:8765        # quick throwaway URL
   # or: tailscale funnel 8765   /   ngrok http 8765

3. In Claude → Settings → Connectors → Add custom connector:

   • URL https://<your-tunnel>/mcp

   • Authentication: None (the server uses a shared header secret, not OAuth)

   • Additional request headers → Add header: X-Paint-Token = <your MCP_PAINT_TOKEN> (Authorization = Bearer <token> also works)

With no MCP_PAINT_TOKEN the server is open to anyone who has the tunnel URL. Set one.

Local Claude Code

.mcp.json (see .mcp.json.example):

{
  "mcpServers": {
    "paint": {
      "command": "/ABS/PATH/NeuroPaint-X/.venv/bin/python",
      "args": ["-m", "mcp_paint"],
      "env": { "MCP_PAINT_TRANSPORT": "stdio" }
    }
  }
}

Tool map

new_canvas · list_canvases · canvas_info · delete_canvas render · export · pick_color · undo · redo add_layer · select_layer · update_layer · delete_layer · duplicate_layer · move_layer · merge_down · clear_layer stroke · draw_rect · draw_ellipse · draw_line · draw_polygon · draw_gradient · bucket_fill · draw_text · place_image · filter_layer batch

Coordinates are pixels, origin top-left. Colors: #rgb / #rrggbb / #rrggbbaa / rgb() / rgba() / CSS names / [r,g,b(,a)].