Allows inspecting and editing a running Krita 6 desktop session, including managing documents and layers, searching brush presets, painting with native brushes, saving .kra files, exporting PNGs, and reading AI Diffusion plugin status and job information.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@krita6-mcp Create a new 800x600 document, add a paint layer, and draw a blue diagonal line"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.
Related MCP server: Krita MCP Server
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.pyIn 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.
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 --jsonInspect targets before editing. Reuse operation_id when retrying an edit, and reconcile timeouts with krita_get_operation. See the usage guide.
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"}' kritaFile 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.
uv run pytest -q
uv run ruff check plugin src tools tests
uv run ruff format --check plugin src tools tests
uv build --no-sourcesLinux 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.pyHost 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.
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-diffusionThe 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.pyVector 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/kritaActivate an existing view of the explicit document so native painting can target it. Changes the user's active canvas. Reuse operation_id on retries.
Inputs: document_id (required), instance_id (required), operation_id (required).
Add an editable rectangle, ellipse, polygon or cubic Bezier shape in image pixels. Solid sRGB fill/stroke or none; active view required. Reinspect for a shape address. Reuse operation_id on retries.
Inputs: node_id (required), geometry (required), document_id (required), instance_id (required), +5 more.
Apply an inspected bridge-owned result to its original active document as a new top paint layer at the generation bounds. Reuse operation_id on retries; does not replace layers or resize the canvas.
Inputs: result_id (required), document_id (required), instance_id (required), operation_id (required), +1 more.
Cancel queued bridge work atomically. For running work this records intent; it cannot stop Krita or cancel a submitted AI Diffusion backend job.
Inputs: instance_id (required), operation_id (required).
Clear the explicit document's selection. No guaranteed undo transaction. Reuse operation_id on retries.
Inputs: document_id (required), instance_id (required), operation_id (required).
Persist specified Generate settings without starting a job. Omitted fields stay unchanged. Requires the pinned add-on and active document; style changes require its local backend. Generation requests still supply their own root prompts/strength/seed and request one image. Reuse operation_id on retries; no guaranteed undo.
Inputs: document_id (required), instance_id (required), operation_id (required), seed, +11 more.
Copy a supported paint layer into an explicit destination document. Omitted parent means document root; above_node_id selects a sibling to insert above. Returns the new node handle. No guaranteed undo transaction. Reuse operation_id to avoid duplicate copies.
Inputs: name (required), node_id (required), document_id (required), instance_id (required), +4 more.
Create a bounded RGBA/U8/sRGB document with an active view (maximum 16 megapixels). Reuse operation_id on retries.
Inputs: name (required), width (required), height (required), instance_id (required), +1 more.
Create a linked PNG/JPEG file layer from a configured input root. Krita watches the source; keep it available. Supports no scaling or fit to image, with Bicubic filtering. No guaranteed undo. Reuse operation_id on retries.
Inputs: name (required), path (required), root (required), document_id (required), +4 more.
Create a group at the top of the explicit parent (document root by default). Returns its handle. Reuse operation_id on retries; no guaranteed undo grouping.
Inputs: name (required), document_id (required), instance_id (required), operation_id (required), +1 more.
Create one named paint layer in an explicit document; return its node UUID.
Inputs: name (required), document_id (required), instance_id (required), operation_id (required), +1 more.
Attach a transparency mask to an explicit paint/group layer, using a copy of the selection or constant canvas opacity. Preserves the canvas selection. Reuse operation_id on retries.
Inputs: name (required), source (required), node_id (required), document_id (required), +2 more.
Create a native editable vector layer in the active document, optionally inside a group. Reuse operation_id on retries; no guaranteed undo grouping.
Inputs: name (required), document_id (required), instance_id (required), operation_id (required), +1 more.
Delete the explicit paint/group/mask node and its bounded subtree. Rejects locked/animated descendants and the last top-level layer. Returns removed handles. Reuse operation_id on retries.
Inputs: node_id (required), document_id (required), instance_id (required), operation_id (required).
Delete one unprotected top-level path shape from an unchanged layer snapshot in the active document. Reuse operation_id; inspect after completion.
Inputs: node_id (required), document_id (required), instance_id (required), shape_index (required), +2 more.
Discover an already loaded Krita AI Diffusion plugin and report integration availability. Does not load plugins or connect to a backend.
Inputs: instance_id (required).
Perform exactly one enabled native undo/redo step on the active document, then await completion. History includes user edits and is not scoped to bridge operations. Reuse operation_id to avoid stepping twice after timeout.
Inputs: direction (required), document_id (required), instance_id (required), operation_id (required).
Edit one top-level path shape using an unchanged layer snapshot. Scale then clockwise rotate about image origin then translate in pixels, composed after its existing transform. Groups/text/protected shapes rejected. Active view required; no guaranteed undo. Reuse operation_id.
Inputs: node_id (required), document_id (required), instance_id (required), shape_index (required), +10 more.
Export a separate PNG under a configured output root while preserving the document's filename association.
Inputs: path (required), root (required), document_id (required), instance_id (required), +2 more.
Raster source-over fill or destination-out erase on a simple RGBA/U8/sRGB paint layer, limited to 1 MP and masked by the current selection. Erase forbids color and uses opacity/selection coverage. Other modes require color. Linear gradient needs end_color/start/end; flood needs point and matches exact layer BGRA with four-connected neighbors. No brush simulation, tolerance, or guaranteed undo. Reuse operation_id.
Inputs: kind (required), node_id (required), document_id (required), instance_id (required), +7 more.
Submit one image through the active document's existing AI Diffusion model and local backend. Inherits canvas selection, regions and controls; strength below 1 refines the canvas. Reuse operation_id on retries. Poll generation_id separately; completion does not automatically apply pixels.
Inputs: document_id (required), instance_id (required), operation_id (required), positive_prompt (required), +4 more.
Poll a bridge-owned generation and obtain stable result handles. Job progress belongs to the add-on; a queued job is not proof of backend admission.
Inputs: document_id (required), instance_id (required), generation_id (required).
Inspect a bridge-owned generated image as an inline PNG without selecting its preview or changing canvas layers. Result handles expire when the add-on removes their images.
Inputs: result_id (required), document_id (required), instance_id (required), generation_id (required), +1 more.
Return an inline PNG of the explicit layer/group projection within canvas bounds. Requires RGBA/U8/standard sRGB; preserves visibility and active layer. Other layers are excluded.
Inputs: node_id (required), document_id (required), instance_id (required), max_edge.
Reconcile a pending or uncertain operation. Read state/effect separately: failure does not prove no changes occurred.
Inputs: instance_id (required), operation_id (required).
Return a settled canvas as an inline PNG with coordinate and color metadata. A pending response can be polled.
Inputs: document_id (required), instance_id (required), max_edge.
Inspect a settled rectangular canvas crop as an inline PNG with image-space offsets. Region must be in canvas and at most 16 megapixels; output edge is at most 1024. Poll pending previews with krita_get_operation.
Inputs: x (required), y (required), width (required), height (required), +3 more.
Import a bounded PNG or JPEG under a configured input root as a new paint layer at an explicit pixel offset. Image must fit the supported RGBA/U8/sRGB destination; no guaranteed undo transaction. Reuse operation_id on retries.
Inputs: name (required), path (required), root (required), document_id (required), +4 more.
Inspect the active document view's brush preset name, size, opacity, flow, rotation, blending, eraser, alpha lock, pressure and foreground color without changing them. Use list_brush_presets for painting handles.
Inputs: document_id (required), instance_id (required).
Read existing AI Diffusion metadata for the explicit document. Does not create diffusion models, change settings, or generate images.
Inputs: document_id (required), instance_id (required).
Inspect document dimensions, color space, editability and layer UUIDs.
Inputs: document_id (required), instance_id (required).
Inspect up to 256 top-level vector shapes and pixel bounds. Returns a layer-state snapshot_id plus shape_index addresses, not persistent shape IDs. Reinspect after edits; identical restored states share a snapshot.
Inputs: node_id (required), document_id (required), instance_id (required).
Search and paginate the current instance's brush preset handles.
Inputs: instance_id (required), limit, query, offset.
Read a bounded page of existing AI Diffusion job metadata for the document. Does not submit, cancel, or apply jobs.
Inputs: document_id (required), instance_id (required), limit, offset.
List available AI Diffusion styles and their handles without changing the current style.
Inputs: instance_id (required).
List live document handles and active-view status in the selected instance.
Inputs: instance_id (required).
Merge a visible, nonanimated paint layer with the adjacent paint layer below it. Requires no masks/children or alpha inheritance on either. Returns the resulting handle after native completion. Reuse operation_id.
Inputs: node_id (required), document_id (required), instance_id (required), operation_id (required).
Merge into the immediately lower sibling vector layer, preserving editable paths and stacking. Requires active view, visible full-opacity normal layers without masks/alpha inheritance, and unprotected visible path shapes. Source is removed after copying; no atomic undo. Reuse operation_id.
Inputs: node_id (required), document_id (required), instance_id (required), operation_id (required).
Refine an existing selection and clip the result to the canvas. Grow/shrink/feather require radius in pixels; invert forbids radius. Reuse operation_id; no guaranteed undo transaction.
Inputs: action (required), document_id (required), instance_id (required), operation_id (required), +1 more.
Reorder a paint layer or group within its document; rejects cycles and locked/animated subtrees. Omitted parent means document root; above_node_id selects a sibling to insert above. Changes stacking order without translating pixels. No guaranteed undo transaction. Reuse operation_id on retries.
Inputs: node_id (required), document_id (required), instance_id (required), operation_id (required), +2 more.
Open a bounded local KRA, PNG or JPEG file from a configured input root and attach an active view. Path must be relative to the named root. Reuse operation_id to avoid duplicate opens after a timeout.
Inputs: path (required), root (required), instance_id (required), operation_id (required).
Paint one native cubic Bézier path with 1–256 segments in image pixels. Each segment is [control1, control2, endpoint], each a coordinate pair. Requires the target's active view; no per-point pressure. Reuse operation_id on retries.
Inputs: color (required), start (required), node_id (required), opacity (required), +6 more.
Paint one native line with integer image coordinates and endpoint pressures. Each call is a separate native stroke.
Inputs: end (required), color (required), start (required), node_id (required), +8 more.
Paint one native brush path in image pixels. Requires the target's active view; no per-point pressure. Reuse the same operation_id for retries.
Inputs: color (required), points (required), node_id (required), opacity (required), +5 more.
Paint one native rectangle/ellipse with explicit brush settings and optional solid foreground fill. Requires active document, pixel brush and no selection. Restores brush context, waits for native completion. Reuse operation_id.
Inputs: x (required), y (required), color (required), shape (required), +10 more.
Read one settled RGBA/U8/sRGB projection pixel from the canvas or explicit node. Returns hex color and alpha without changing foreground color.
Inputs: x (required), y (required), document_id (required), instance_id (required), +1 more.
Save editable .kra work under a configured output root. Path is relative; replacing an existing file requires overwrite=true.
Inputs: path (required), root (required), document_id (required), instance_id (required), +2 more.
Replace the root or single-linked region's entire conditioning list; [] clears it. Entries reference existing image layers, with mode, strength 0..2 in steps of 0.02, and 0<=start<=end<=1. Does not generate control maps or images. Inspect is_supported before generation. Requires active Generate document. Reuse operation_id; no guaranteed undo.
Inputs: controls (required), document_id (required), instance_id (required), operation_id (required), +1 more.
Create/update a prompt region linked directly to an existing paint/group layer, or remove that region and its controls without deleting artwork. A prompt is required unless removing. Rejects ambiguous/multiple links. Requires active Generate document. Reuse operation_id; no guaranteed undo.
Inputs: node_id (required), document_id (required), instance_id (required), operation_id (required), +2 more.
Replace a file layer's linked PNG/JPEG source and scaling, using a configured input root. Uses Bicubic filtering. Source must remain available; no guaranteed undo. Reuse operation_id on retries.
Inputs: path (required), root (required), node_id (required), document_id (required), +3 more.
Set paint/group/mask/file/vector-layer name, visibility, or opacity in [0,1]; paint/group/file/vector-layer blend mode and alpha inheritance; paint-layer alpha lock. No guaranteed undo transaction or atomic multi-property rollback. Reuse operation_id on retries.
Inputs: node_id (required), document_id (required), instance_id (required), operation_id (required), +6 more.
Replace or combine the selection with a bounded rectangle or polygon in image pixels. Rectangle requires only x/y/width/height; polygon requires only 3–256 integer points. Selection bounds must fit the canvas and 16 megapixels. No guaranteed undo transaction.
Inputs: shape (required), document_id (required), instance_id (required), operation_id (required), +6 more.
Replace an existing transparency mask's coverage with a selection copy or constant canvas opacity. Reuse operation_id; no guaranteed undo transaction.
Inputs: source (required), node_id (required), document_id (required), instance_id (required), +1 more.
Discover reachable Krita bridges, exact versions, capabilities and queue health. No document changes.
Inputs: instance_id.
Transform the entire document, bounded to 8192 per side/16 MP. Crop/resize require x,y,width,height; resize uses the new canvas rectangle in old image coordinates. Scale requires width,height and optional filter. Rotate requires degrees; flip requires axis and active document. Rejects unrelated fields and locked/animated nodes. Reuse operation_id.
Inputs: action (required), document_id (required), instance_id (required), operation_id (required), +7 more.
Resample one supported RGBA/U8/sRGB paint layer: scale then clockwise rotate around an explicit image-pixel pivot, then translate. This rewrites raster pixels with no guaranteed undo transaction; it is not a native transform mask. Reuse operation_id on retries.
Inputs: pivot (required), node_id (required), document_id (required), instance_id (required), +6 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 56 tools
Most tools target a distinct resource/action—documents, layers, selections, vector shapes, diffusion jobs—and descriptions explicitly separate inspection from mutation. A few preview/paint and diffusion-result tools are close in name, but their semantics are clear enough to avoid serious mis-selection.
The krita_ prefix and snake_case verb_noun style are consistent across the set. Minor deviations like krita_status and krita_diffusion_status, plus mixed read verbs (list/get/inspect), keep it from a perfect 5.
56 tools is an extreme surface for an MCP server, far above the 3–15 sweet spot and even beyond the 25+ 'heavy' band. The set would be more manageable split into focused document, layer, vector, and diffusion servers.
The surface is unusually broad: documents, layers, painting, selection, canvas transforms, vector shapes, history, and AI diffusion all have usable create/read/update/delete flows. Minor gaps such as document close/delete and layer-lock toggling remain, but they are workable.
Lets AI assistants draw: logos, posters, illustrations and scenes, as editable SVG and PNG.
Create images, video and audio; reuse assets and build Canvas workflows from your AI assistant.
Agent-Native design tool - create and edit visual designs with agent assistance
Image and video AI tools and your own pipelines, run from any AI assistant.