The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Krita Codex MCP listing page.
Control Krita from OpenAI Codex through a secure local Model Context Protocol (MCP) server for Windows.
PyPI package · GitHub releases · Windows installation guide
A Windows-first local MCP server that lets Codex inspect and control Krita through a small,
authenticated bridge. The MCP process uses STDIO. The Krita Python plugin listens only on
127.0.0.1, validates a shared bearer token, and dispatches every Krita API call to Qt's main
thread.
This repository is a Windows-first integration with a capability-based runtime compatibility check. Krita 5.3.2.1 is a tested build, not a hard version requirement. The server deliberately exposes a small set of cohesive tools instead of a large collection of micro-tools:
| Tool | Purpose |
|---|---|
krita_state | Active document, canvas/color space, recursive layer tree with UUIDs, active layer and current painting state |
krita_preview | Whole-canvas or pixel-precise cropped PNG returned directly as MCP image content |
krita_canvas | Sample colors; resize, scale, crop, rotate or flip; import editable raster layers |
krita_edit | Create/refine/move selections; native copy, cut, paste, selection-to-layer, fill and clear |
krita_document | Inspect runtime compatibility; list, create, open, activate, save and close documents |
krita_layers | Read/edit the layer tree, safely reparent, and transform layers by stable UUID |
krita_history | Read undo/redo state and execute bounded undo or redo steps |
krita_brush | Read/set native brush state and search installed Krita presets |
krita_paint_path | Pressure-aware line segments through Krita's native Node.paintLine API and active brush preset |
krita_draw | Native preset-backed lines, open/closed paths, polygons, rectangles and ellipses |
krita_color | KRA-backed project palettes, Krita palette swatches, color replacement and safe correction filters |
krita_asset | Export layer PNGs plus Unity-oriented animation, tileset and named-region packages with direct previews |
krita_save_export | Save KRA and export PNG beneath configured roots only |
The bridge has no arbitrary Python execution tool and no direct pixel painting fallback. Actual
painting, shapes, replacement fills and correction filters go through native Krita actions or
stroke APIs. If the running Krita build lacks a feature, krita_state and
krita_document(action="compatibility") report the affected tools. Calling that feature returns a
structured error; the bridge never silently switches to a different rendering backend.
A first-time setup has two separate parts: the local bridge must be installed and enabled in Krita,
then Codex must be connected through either the marketplace plugin or a direct MCP configuration.
The codex plugin commands do not install or enable anything in Krita.
This requires a Windows Krita build that passes the live compatibility check and
uv/uvx on PATH.
Ready for productive use. or the explicit limited-mode success message.The repository includes a public, local-first Codex plugin. It bundles the guided krita-control
skill and starts the version-pinned PyPI MCP server through uvx; Krita and the authenticated bridge
continue to run only on the user's machine. Run these commands only after the Krita bridge has been
installed, enabled, restarted, and checked as described above. They register the GitHub marketplace
and install the Codex bundle; they do not modify the Krita installation or enable its Python plugin.
Start a new Codex task after installation, then verify krita_state and krita_preview. Plugin users
should not also add a separate [mcp_servers.krita] block because the plugin already provides that
server. For later repository releases, run codex plugin marketplace upgrade krita-codex, rerun
codex plugin add krita-codex-mcp@krita-codex, and start another new Codex task.
If you do not want to install the marketplace plugin, use this alternative only after the Krita
bridge has passed the live check. Preview the checkout-free, exactly version-pinned uvx Codex
block with krita-codex-install codex-config. Apply it only after explicit confirmation, restart
Codex, verify krita_state and krita_preview, and only then start normal work.
Install and update never close Krita. If the authenticated bridge is running, replacement is rejected before any installed files are changed and Krita must be closed manually. A busy local bridge port also stops the installer before replacement begins.
For a personal installation, use the user-level C:\Users\<you>\.codex\config.toml. This is the
recommended option because the server is then available to all local Codex tasks and Git
worktrees. The generated block uses uvx, has no checkout cwd, and pins the same exact
distribution version as the installed plugin. The installer only changes that file after showing
the full preview and receiving explicit confirmation. Unmarked or conflicting Krita entries are
never overwritten. Never commit personal configuration. See the
Windows installation guide for details.
The preflight checks local configuration, the complete installed hash manifest, wheel/plugin/ protocol versions, loopback port, authentication and the running Krita capability profile. The running plugin reports the distribution, protocol and Krita versions without adding an MCP tool. The check creates a disposable document, verifies a new paint layer, native drawing, Undo/Redo, transactional reparenting, direct PNG preview bytes and temporary KRA/PNG output beneath an allowed root. It restores the previously active document and removes every temporary file.
An unknown Krita version is accepted when all critical capabilities pass. Missing optional
features produce limited warnings naming the affected MCP tools; missing projection, persistence,
stable layer-tree or document-lifecycle APIs remain critical. The same structured report is
available to Codex through krita_state, so it can avoid unavailable operations.
The current release supports native preset-backed painting and shapes, persistent document and
layer editing, selections, color operations, KRA/PNG output, and Unity-oriented animation,
tileset and named-region packages. Preview and asset operations return PNG images directly to the
MCP caller. Re-export preserves Unity .meta sidecars for stable generated filenames.
The tested Krita 5.3.2.1 build imposes several safety limits. Other builds are evaluated at runtime and may report different available features:
checkpoint_reopen=true can perform that round trip automatically.Node.paintLine requires integer QPoint values, so incoming canvas coordinates are rounded at
the native API boundary.Timeouts are operation-specific across Codex, the MCP BridgeClient, the local HTTP bridge and
Qt's main-thread dispatcher:
| Operation class | Dispatcher timeout |
|---|---|
| Reads and normal edits | 30 seconds |
| Document open and checkpoint save | 120 seconds |
| KRA/PNG, layer, animation, tileset and region exports | 180 seconds |
The recommended Codex tool_timeout_sec is 210 seconds so the MCP client can receive the bridge's
structured result. If a timed-out Qt operation is already running, operation_may_complete=true
is preserved and later calls receive BRIDGE_BUSY until Krita actually finishes.
Keep allowed_roots as narrow as practical, keep ordinary versioned or manual KRA backups, and
do not treat the bridge timeout as cancellation. The bridge is local-only and binds exactly to
127.0.0.1.
See Windows installation, tool behavior and limits, security, and the GitHub releases.
Released under the MIT License. Copyright (c) 2026 Nicklas Desens.