krita6-mcp

Inspect documents, paint with Krita's native brushes, preview the canvas, and save editable artwork through MCP.

Early alpha, 0.1.0 unreleased. Tested on Linux/Krita 6.0.3 with small documents and one pixel-brush preset. Windows is unsupported; macOS is untested. See supported behavior and limits.

What works

• Document/layer inspection and creation, preset search, native paths and lines with endpoint pressure.

• Document activation, rectangle/polygon selections, and native cubic Bézier paths.

• Native vector shapes, editing and vector-layer merging, preserving editable vectors in .kra files.

• Layer/group/mask organization, compositing, copying, ordering, merging, and bounded affine transforms.

• Selection combination/refinement, canvas transforms, native shapes, raster fills/erasing, and single-step undo/redo.

• Inline whole-canvas/region/layer PNG previews, color and brush inspection, bounded image import/open, layered .kra saves, and PNG export.

• Optional AI Diffusion generation: configure settings, regions and control/reference layers, generate, inspect results, and apply as a new layer.

Install

Requires Krita 6 with Python plugins and PyQt6, external Python 3.10+, and uv. The MCP environment stays separate from Krita's embedded Python.

git clone https://github.com/fanzhuyifan/krita6-mcp.git
cd krita6-mcp
uv sync --locked
uv run python tools/build_plugin.py

In Krita, import dist/krita6-bridge-0.1.0.zip through Tools → Scripts → Import Python Plugin from File, then restart. Enable Krita 6 MCP Bridge in Settings → Configure Krita → Python Plugin Manager and restart again.

The bridge starts automatically. Start/Stop/Status controls are under Tools → Scripts. See setup, upgrades, and removal for details.

Connect an MCP client

Configure a stdio server using your checkout's absolute Python path:

{
  "mcpServers": {
    "krita6": {
      "command": "/absolute/path/to/krita6-mcp/.venv/bin/python",
      "args": ["-m", "krita6_mcp.cli", "serve"]
    }
  }
}

With Krita running, check the connection:

uv run krita6-mcp doctor --json

Inspect targets before editing. Reuse operation_id when retrying an edit, and reconcile timeouts with krita_get_operation. See the usage guide.

Save and export

Fully exit Krita, create an output directory, and relaunch with that directory configured:

mkdir -p /absolute/path/to/artwork
KRITA6_MCP_OUTPUT_ROOTS='{"art":"/absolute/path/to/artwork"}' krita

File tools use root="art" and a relative path. Replacing files requires overwrite=true. Painting and previews work without output roots. Opening PNG/JPEG/KRA files, importing PNG/JPEG layers, or creating/relinking native file layers uses separate KRITA6_MCP_INPUT_ROOTS configured the same way. File configuration and reference editing.

Development and verification

uv run pytest -q
uv run ruff check plugin src tools tests
uv run ruff format --check plugin src tools tests
uv build --no-sources

Linux host checks require Krita, Xvfb, xauth, and D-Bus. Run from a shell without an activated Python environment or conflicting KDE development paths:

.venv/bin/python tools/probe_krita.py
.venv/bin/python tools/smoke_krita.py
.venv/bin/python tools/probe_editing.py  # Includes linked file-layer creation, relink, scaling, save/reopen
.venv/bin/python tools/probe_plugin_import.py

Host probes use isolated profiles and scratch files. AI Diffusion backend tests require separately installed local models. CI tests the external runtime on Python 3.10, 3.12, and 3.14; native compatibility requires the live probes. See testing instructions and contributing.

Development approach

Developed primarily with AI coding agents. Review and additional compatibility testing are welcome.

MIT · Independent of KDE/Krita and Krita AI Diffusion.

Issues · Security · Design · Acknowledgments · Changelog

Diffusion configuration validation (isolated profile and scratch document; no backend needed):

.venv/bin/pytest -q tests/unit tests/integration
.venv/bin/python tools/probe_diffusion.py --source /absolute/path/to/pinned/krita-ai-diffusion

The testing guide documents host prerequisites and the separate local-backend generation/style probe.

General editing now includes groups/transparency masks, compositing, deletion/merge, single-step undo/redo, selection combination/refinement, canvas transforms, native shapes, raster fills/erasing, and layer/color/brush inspection. See scope and limits.

Run its independent live-host probe with an isolated profile and scratch documents:

.venv/bin/python tools/probe_general_editing.py

Vector editing and merge validation (isolated profile and scratch documents):

env -u PYTHONPATH -u LD_LIBRARY_PATH -u QT_PLUGIN_PATH \
  .venv/bin/python tools/probe_vector_editing.py --krita /usr/bin/krita