Krita Codex MCP

Krita Codex MCP サーバー

Windows および Linux 向けの安全なローカル Model Context Protocol（MCP）サーバーを介して、OpenAI Codex から Krita を操作できます。

PyPI パッケージ · GitHub リリース · Windows インストールガイド · Linux インストールガイド · Codex と MCP の互換性

小規模な認証済みブリッジを介して、Codex から Krita の状態を確認し、操作できるローカル MCP サーバーです。MCP プロセスは STDIO を使用します。Krita Python プラグインは 127.0.0.1 のみで待ち受け、共有ベアラートークンを検証し、すべての Krita API 呼び出しを Qt のメインスレッドに振り分けます。

Windows は当初からサポートされているプラットフォームで、Linux のサポートは実験的です。 どちらのプラットフォームでも、機能ベースのランタイム互換性チェックを使用します。Windows 版 Krita 5.3.2.1 はテスト済みのビルドであり、必須バージョンではありません。このサーバーは、多数の細かなツールではなく、まとまりのある少数のツールを公開するよう意図的に設計されています。

ツール	目的
krita_state	アクティブなドキュメント、キャンバス／カラースペース、UUID を含む再帰的なレイヤーツリー、アクティブレイヤー、現在の描画状態
krita_preview	キャンバス全体、またはピクセル単位で正確に切り抜いた PNG を MCP 画像コンテンツとして直接返します
krita_canvas	色のサンプリング、サイズ変更、拡大縮小、切り抜き、回転、反転、編集可能なラスターレイヤーのインポート
krita_edit	選択範囲の作成／調整／移動、ネイティブのコピー、切り取り、貼り付け、選択範囲からのレイヤー作成、塗りつぶし、クリア
krita_document	ランタイム互換性の確認、ドキュメントの一覧表示、作成、開く、アクティブ化、保存、閉じる
krita_layers	レイヤーツリーの読み取り／編集、安全な親の変更、安定した UUID によるレイヤーの変形
krita_history	元に戻す／やり直し状態の読み取り、上限付きの元に戻す／やり直しの実行
krita_brush	ネイティブのブラシ状態の読み取り／設定、インストール済み Krita プリセットの検索
krita_paint_path	Krita のネイティブ Node.paintLine API とアクティブなブラシプリセットを使用した、筆圧対応の線分
krita_draw	ネイティブプリセットに基づく線、開いた／閉じたパス、多角形、長方形、楕円
krita_color	KRA に保存されたプロジェクトパレット、Krita のパレットスウォッチ、色の置換、安全な補正フィルター
krita_asset	レイヤー PNG のエクスポートに加え、Unity 向けのアニメーション、タイルセット、名前付き領域のパッケージをプレビュー付きで直接出力
krita_save_export	設定済みのルートディレクトリ以下に KRA を保存し、PNG をエクスポート

Codex -> local STDIO MCP process -> authenticated 127.0.0.1 HTTP bridge
      -> queued, timeout-aware Qt main-thread dispatch -> Krita Python API

このブリッジには、任意の Python を実行するツールも、ピクセルを直接描画する代替手段もありません。実際の描画、図形、置換塗りつぶし、補正フィルターは、ネイティブの Krita アクションまたはストローク API を介して実行されます。実行中の Krita ビルドに機能がない場合は、krita_state と krita_document(action="compatibility") が該当するツールを報告します。その機能を呼び出すと、構造化エラーが返されます。ブリッジが別のレンダリングバックエンドに暗黙に切り替わることはありません。

クイックスタート

お使いのプラットフォームに合わせて、インストール元を選択してください。

プラットフォーム	インストール元	検証
Windows	PyPI 0.2.2 またはチェックアウト	Windows CI；Krita 5.3.2.1 でのオリジナルの実機テスト
Linux	PyPI 0.2.2 またはチェックアウト	Linux CI；制限モードで Debian 13 / Krita 5.2.9 を使ったコントリビューターによる実機テスト

バージョン 0.2.2 には、Linux/XDG パスとプライベート設定に関する修正が含まれています。インストーラー、 Krita プラグイン、Codex サーバーは、必ず同じバージョンに揃えてください。マーケットプレイスランチャーも同じバージョンに固定されています。 その他の Linux ディストリビューションや Krita ビルドでは、それぞれ実機での事前チェックが必要です。

初回セットアップは、2 つの別々の作業で構成されます。まずローカルブリッジを Krita にインストールして有効にし、 次にマーケットプレイスプラグインまたは直接 MCP 設定を使って Codex を接続します。 codex plugin コマンドでは、Krita へのインストールや有効化は行われません。

Krita には Python スクリプト機能が含まれている必要があります。また、実機互換性チェックに合格し、 uv/uvx が PATH に含まれている必要があります。 MCP プロセスは Krita と同じコンピューターで実行してください。ローカルの Codex CLI、IDE、サポート対象のデスクトップクライアントではローカル MCP 設定を使用します。 ホスト型の ChatGPT ウェブチャットは、この GitHub リポジトリを追加しても、このコンピューターの 127.0.0.1 ブリッジには接続できません。

Windows：公開パッケージ

1. Krita を終了し、許可するディレクトリがすでに存在することを確認してから、PyPI から最新リリースをインストールします。

uvx --from "krita-codex-mcp==0.2.2" `
  krita-codex-install install `
  --allowed-root "C:\Krita Work"

2. Krita で 設定 > Krita の設定 > Python プラグインマネージャー を開き、 Krita Codex Bridge を有効にします。
3. Krita を終了して再起動し、インストールしたプラグインと共有プロトコルパッケージを同時に読み込みます。
4. 同じバージョンの実機チェックを実行します。

uvx --from "krita-codex-mcp==0.2.2" krita-codex-install check

5. Ready for productive use. または明示的に表示された制限モードの成功メッセージが表示されることを確認します。
6. 以下から Codex の接続方法を 1 つだけ選択してください。マーケットプレイスプラグインまたは直接 MCP 設定です。

Linux：PyPI パッケージ

Krita を終了し、対象を絞った許可ディレクトリを作成してから、PyPI からインストールします。

mkdir -p "$HOME/krita-codex-work"
uvx --from "krita-codex-mcp==0.2.2" krita-codex-install install --allowed-root "$HOME/krita-codex-work"

Krita の Python プラグインマネージャー で Krita Codex Bridge を有効にし、Krita を終了して再起動してから、次を実行します。

uvx --from "krita-codex-mcp==0.2.2" krita-codex-install check

compatible または明示的に報告された limited モードを受け入れてください。いずれかの接続方法については、 Linux ガイドの Codex セットアップに従ってください。 インストーラーは XDG ディレクトリを使用し、トークン設定をプライベートに保ちます。sudo は不要です。

GitHub から Codex プラグインをインストールする

このリポジトリには、パブリックでローカルファーストの Codex プラグインが含まれています。ガイド付きの krita-control スキルをバンドルし、バージョンを固定した PyPI MCP サーバーを uvx 経由で起動します。Krita と認証済みブリッジは、 引き続きユーザーのコンピューター上でのみ実行されます。次のコマンドは、上記の手順に従って Krita ブリッジを インストール、有効化、再起動し、チェックした後にのみ実行してください。これらのコマンドは GitHub マーケットプレイスを登録して Codex バンドルをインストールしますが、Krita のインストール環境を変更したり、Python プラグインを有効にしたりすることはありません。

codex plugin marketplace add cyyprezz/krita-codex-mcp
codex plugin add krita-codex-mcp@krita-codex

インストール後、新しい Codex タスクを開始し、krita_state と krita_preview を確認します。プラグインを使用する場合は、 プラグインがすでにそのサーバーを提供しているため、別途 [mcp_servers.krita] ブロックを追加しないでください。 以降のリポジトリリリースに更新するには、codex plugin marketplace upgrade krita-codex を実行し、 codex plugin add krita-codex-mcp@krita-codex を再実行して、もう一度新しい Codex タスクを開始してください。

MCP サーバーを直接設定する

どちらのプラットフォームでも、この方法を使うのは、Krita ブリッジのライブチェックに合格した後に限ります。チェックアウト不要でバージョンが厳密に固定された uvx Codex ブロックを krita-codex-install codex-config でプレビューします。明示的な確認を行ってから適用し、Codex を再起動して krita_state と krita_preview を確認してから、通常の作業を開始してください。

インストールと更新によって Krita が終了することはありません。認証済みブリッジが稼働中の場合、インストール済みファイルを変更する前に置き換えが拒否されるため、Krita は手動で終了する必要があります。ローカルブリッジのポートが使用中の場合も、置き換えの開始前にインストーラーが停止します。

個人用にインストールする場合は、Linux ではユーザーレベルの ~/.codex/config.toml、Windows では C:\Users\<you>\.codex\config.toml を使用してください。サーバーがすべてのローカル Codex タスクと Git ワークツリーから利用できるため、この方法を推奨します。生成されるブロックは uvx を使用し、チェックアウトの cwd を持たず、インストール済みプラグインと同じ配布バージョンを厳密に固定します。インストーラーがこのファイルを変更するのは、プレビュー全体を表示し、明示的な確認を受けた後だけです。マークのない Krita エントリや競合する Krita エントリは上書きされません。個人用の設定は決してコミットしないでください。詳細はWindows インストールガイドを参照してください。

生成されるランチャーとマーケットプレイス設定は、カスタム XDG ディレクトリを明示的に転送します。Codex と Krita には同じ値を継承させる必要があります。未リリースのソース変更を使用する場合は、Linux ガイドにあるチェックアウト固有の方法を使用してください。

現在の Codex と MCP の互換性

互換性チェックでは、Codex CLI 0.163.0（2026-10-15 リリース）をビルド済み wheel に対して実行し、API キー、モデルリクエスト、起動中の Krita がなくても、13 個すべてのツールが検出されることを確認します。適用範囲の詳細は互換性に関する注記を参照してください。

このサーバーは、MCP Python SDK 1.x のメンテナンス系統（mcp<2）を意図的に使用し続けています。現在の Codex は、この SDK が使用する従来の STDIO ハンドシェイクを引き続きサポートしています。新しい MCP 2026-07-28 プロトコルと移植可能なプラグイン形式は、それだけで、正常に動作しているこのローカル統合を置き換える必要があることを意味しません。既存の Codex プラグインマニフェストは、引き続きサポートされる互換形式です。新しい MCP プロトコル機能を完全にサポートするには、別途、テストを行った SDK 移行が必要です。

プリフライトでは、ローカル設定、インストール済みファイルの完全なハッシュマニフェスト、wheel／プラグイン／プロトコルの各バージョン、ループバックポート、認証、稼働中の Krita の機能プロファイルを確認します。稼働中のプラグインは、MCP ツールを追加することなく、配布バージョン、プロトコルバージョン、Krita バージョンを報告します。このチェックでは使い捨てのドキュメントを作成し、新しいペイントレイヤー、ネイティブ描画、Undo／Redo、トランザクションによる親子関係の変更、PNG プレビューの直接バイト列、許可されたルート配下への一時的な KRA／PNG 出力を検証します。以前アクティブだったドキュメントを復元し、一時ファイルをすべて削除します。

重要な機能がすべて合格すれば、Krita のバージョンが不明でも受け入れられます。オプション機能が不足している場合は、影響を受ける MCP ツールを示す limited 警告が表示されます。投影、永続化、安定したレイヤーツリー、ドキュメントのライフサイクルに関する API の不足は、引き続き重大な問題として扱われます。同じ構造化レポートは krita_state を通じて Codex から利用できるため、利用できない操作を回避できます。

機能と Krita の制限

現在のリリースでは、ネイティブのプリセットに基づく描画と図形、ドキュメントおよびレイヤーの永続的な編集、選択範囲、色操作、KRA/PNG 出力、Unity 向けのアニメーション、タイルセット、名前付き領域のパッケージに対応しています。プレビューとアセット操作では、PNG 画像が MCP 呼び出し元に直接返されます。再エクスポートでは、生成されたファイル名の安定性を保つため、Unity の .meta サイドカーファイルが維持されます。

テスト済みの Krita 5.3.2.1 ビルドには、いくつかの安全上の制限があります。他のビルドは実行時に評価され、利用可能な機能が異なる場合があります。

• レイヤーの自由変形による拡大縮小、回転、せん断、切り抜きの操作は、ネイティブの Undo コマンドではありません。ブリッジは非表示のバックアップレイヤーを作成し、KRA を保存、終了して再度開くまで、2 回目の直接変形をブロックします。checkpoint_reopen=true を指定すると、この往復処理を自動で実行できます。
• 変形マスクは、開いているドキュメントごとに 3 つまでに制限されています。Krita を再起動するまで、同じセッション内でのマスクの変更と削除、およびマスクと直接変形のバックエンドの併用はブロックされます。
• Node.paintLine では整数の QPoint 値が必要なため、受信したキャンバス座標はネイティブ API の境界で丸められます。
• PNG エクスポートでは、フォーマット選択ダイアログがローカルブリッジをブロックしないよう、Krita のバッチモードを一時的に有効にします。

タイムアウトと本番環境向けの安全策

タイムアウトは、Codex、MCP の BridgeClient、ローカル HTTP ブリッジ、Qt のメインスレッドディスパッチャーにおいて、操作ごとに設定されています。

操作クラス	ディスパッチャーのタイムアウト
読み取りと通常の編集	30 秒
ドキュメントを開く操作とチェックポイントの保存	120 秒
KRA/PNG、レイヤー、アニメーション、タイルセット、領域のエクスポート	180 秒

推奨される Codex の tool_timeout_sec は 210 秒です。これにより、MCP クライアントはブリッジの構造化された結果を受け取れます。タイムアウトした Qt 操作がすでに実行中の場合、operation_may_complete=true は維持され、Krita の処理が実際に完了するまで、後続の呼び出しには BRIDGE_BUSY が返されます。

allowed_roots は可能な限り狭く設定し、通常のバージョン管理されたバックアップまたは手動の KRA バックアップを保持してください。また、ブリッジのタイムアウトをキャンセルとして扱わないでください。ブリッジはローカル専用で、127.0.0.1 にのみバインドされます。

Windows のインストール方法、Linux のインストール方法、Codex/MCP の互換性、ツールの動作と制限、セキュリティ、GitHub リリースを参照してください。

ライセンス

MIT Licenseの下で公開されています。Copyright (c) 2026 Nicklas Desens.