Krita MCP v4

This v4 implementation is built from nanayax3/krita-mcp.

This canonical NixOS/Krita 6 bridge is a strict protocol-v4 implementation. It contains:

• a PyQt6 Krita plugin with loopback HTTP endpoints;

• an asynchronous, typed FastMCP 4.0.3 server;

• contract and security tests that run without importing Krita.

There is no v3 or pixel-paint compatibility surface.

Install

Copy krita-plugin/kritamcp/ and krita-plugin/kritamcp.desktop into Krita's Python plugin directory, enable “Krita MCP Bridge” in the Python Plugin Manager, and restart Krita. Install the wrapper environment with:

python -m venv .venv
.venv/bin/pip install -r requirements.txt

Configure the MCP client to run this repository's server.py.

Related MCP server: Krita Illustration MCP

Security and transport

The plugin binds only to 127.0.0.1:5678. At startup it creates a random 256-bit bearer token at $XDG_RUNTIME_DIR/krita-mcp/token with mode 0600. The token is required for /v4/capabilities and /v4/command and is never logged. /health is the only unauthenticated endpoint.

The bridge validates request size, action names, queue depth, revisions, request-id retries, stroke batch limits, and allowlisted resolved paths. One session owns the writer lease; disconnect or timeout releases it without closing the document.

Protocol

See docs/API.md. The command envelope contains protocol version, request/session IDs, optional document ID, expected revision for every write, an action, and parameters. Mutating replies are cached by request ID within the session, making retries idempotent.

Documents created by v4 are RGBA/U16, 300 PPI, using sRGB-elle-V2-srgbtrc.icc. KRA save and PNG export are separate operations. Projection capture explicitly converts to 8-bit sRGB.

Painting accepts one native paintLine per line stroke or one native cubic paintPath per curved stroke. Every stroke supplies complete brush state. Line pressure is supported; cubic pressure, tilt, rotation, and speed are rejected. Candidate transactions use ephemeral paint layers and never snapshot a full U16 canvas.

Verification

python -m unittest discover -s tests -v

Headless tests cover schemas, authentication, idempotency, revision conflicts, path/symlink traversal, resource identity, unsupported sensors, limits, transaction ownership, and source-level native painting invariants. Live Krita verification requires the user-started application and plugin.

License

MIT