home / mcp / paint mcp server

Paint MCP Server

Exposes a drawing canvas as an MCP server enabling an LLM to paint on a pygame window via tool calls.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "joeyballentine-paint-mcp": {
      "command": "python",
      "args": [
        "server.py"
      ]
    }
  }
}

Paint MCP exposes a drawing canvas as an MCP server. An LLM can connect over stdio to issue painting commands that render on a pygame window, enabling dynamic, AI-assisted art creation through a structured set of tools.

How to use

To use the Paint MCP server, start the local MCP process and connect using any MCP-compatible client. The server runs a pygame-based canvas and listens for drawing commands sent by the client. The workflow typically looks like this: start the server, connect your MCP client, and begin issuing tool calls to paint, draw shapes, or apply oil painting effects.

How to install

Prerequisites: you need Python and an internet connection to install dependencies.

pip install -r requirements.txt

Additional content

The server provides a suite of drawing tools that you can invoke from your MCP client. It includes basic drawing primitives, color and brush controls, and an oil painting mode for painterly effects. The server uses a pygame canvas of 800 by 600 pixels and supports an undo stack and canvas saving.

Usage example commands

python server.py

Oil painting features

When oil paint mode is enabled, color mixing, paint depletion, soft edges, and brush shape variations create a realistic painting workflow. Rectangles, ellipses, and flood fill are blocked in oil paint mode, so you focus on points, lines, and paths for painting.

Examples

Regular mode and oil paint mode provide different artistic capabilities. Use batch strokes to efficiently send many small actions with per-stroke attributes.

Architecture

Key components include the entry point that runs the pygame loop, a tool definition module that queues commands, and a drawing engine that renders strokes and manages the undo stack.

Available tools

get_canvas_info

Retrieve current canvas dimensions, active color, brush size, and active drawing mode.

set_color

Set the active drawing color using RGB components (0-255 range).

set_brush_size

Adjust the brush size in pixels (range 1-50).

set_brush_shape

Choose the brush shape from round, flat, filbert, fan, or palette_knife to influence stroke texture.

draw_point

Draw a single pixel or point at a specified coordinate.

draw_line

Render a straight line between two coordinates.

draw_rect

Draw a rectangle outline or filled shape; note that it may be blocked in oil paint mode.

draw_ellipse

Draw an ellipse shape; note that it may be blocked in oil paint mode.

draw_path

Stroke a freehand path defined by sequential coordinate pairs.

batch_strokes

Execute multiple strokes in a single call, with per-stroke overrides for color, size, and shape.

blend_path

Smudge or blend colors along a path to create soft transitions.

flood_fill

Bucket-fill an area with the current color; may be blocked in oil paint mode.

clear_canvas

Reset the canvas to a white background.

undo

Rollback the most recent operation to restore previous canvas state.

get_canvas_pixels

Read raw pixel data from a specified region of the canvas.

preview_canvas

Save the current canvas to a temporary PNG file and return its path for quick inspection.

save_canvas

Persist the current canvas as a PNG file on disk.

set_oil_paint_mode

Toggle oil paint simulation on or off to enable painterly effects.

get_oil_painting_guide

Provide a technique guide for achieving realistic oil painting results.