Krita MCP Server

Local Krita 6 version

This local copy is maintained for the NixOS Krita 6 installation. Krita 6 embeds PyQt6, so krita-plugin/kritamcp/__init__.py uses PyQt6 imports. The plugin still listens on http://localhost:5678 when enabled in Krita.

Let AI paint in Krita via the Model Context Protocol.

This bridge allows Claude (or any MCP client) to create canvases, paint strokes, draw shapes, export images, and more — all inside a running Krita instance.

How It Works

Two components:

1. Krita Plugin (krita-plugin/) — A Python plugin that runs inside Krita, exposing an HTTP server on localhost:5678. It receives paint commands and executes them on Krita's main thread via a command queue.

2. MCP Server (server.py) — A FastMCP server that exposes painting tools to any MCP client. It translates MCP tool calls into HTTP requests to the Krita plugin.

MCP Client (Claude, etc.)  ←→  MCP Server (server.py)  ←→  Krita Plugin (HTTP on :5678)  ←→  Krita

See docs/API.md for the HTTP envelope, legacy actions, v3 native surface, transaction semantics, and limits.

Setup

1. Install the Krita Plugin

Copy the plugin files to your Krita plugins directory:

Copy both:

• krita-plugin/kritamcp/ (the folder with __init__.py)

• krita-plugin/kritamcp.desktop

Then in Krita: Settings → Configure Krita → Python Plugin Manager → Enable "Krita MCP Bridge" and restart Krita.

2. Install the MCP Server

pip install fastmcp httpx

Or with a virtual environment:

python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt

3. Configure Your MCP Client

Add to your MCP client config (e.g., Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "krita": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}

If using a virtual environment:

{
  "mcpServers": {
    "krita": {
      "command": "/path/to/.venv/Scripts/python",
      "args": ["/path/to/server.py"]
    }
  }
}

Available Tools

The Export Timeout Fix

This is the main reason this repo exists.

By default, HTTP requests and command queue operations time out after ~30 seconds. Canvas export (get_canvas) and file save (save) operations can easily exceed this on larger canvases, causing silent failures or timeout errors.

The fix is applied in two places:

MCP Server (server.py) — Extended timeout for export/save commands:

# In krita_get_canvas and krita_save:
result = send_command("get_canvas", {"filename": filename}, timeout=120.0)
result = send_command("save", {"path": path}, timeout=120.0)

Krita Plugin (__init__.py) — Matching timeout in the command queue:

def get_result(self, command_id, timeout=120):
    """Wait for result with timeout."""
    for _ in range(int(timeout * 10)):  # Check every 100ms
        ...

Both sides must match. If only the MCP server timeout is increased, the plugin's command queue will still time out at 30s. If only the plugin timeout is increased, the HTTP request from the MCP server will time out first.

Configuration

Painting Approach

The plugin paints using direct pixel manipulation (not Krita's native brush engine for strokes). This means:

• Strokes use a custom soft-circle renderer with configurable hardness

• Alpha blending is done manually in BGRA pixel format

• Shapes (rectangle, ellipse, line) are rasterized directly

• This approach is reliable and doesn't depend on Krita's internal brush state

The set_brush tool does set Krita's brush preset (for potential future use), but stroke currently uses its own pixel-level rendering.

License

MIT