Krita Codex MCP

Krita Codex MCP 服务

通过安全的本地 Model Context Protocol（MCP）服务，在 Windows 和 Linux 上通过 OpenAI Codex 控制 Krita。

PyPI 软件包 · GitHub 发行版 · Windows 安装指南 · Linux 安装指南 · Codex 与 MCP 兼容性

本地 MCP 服务通过小型认证桥接器，让 Codex 能够检查和控制 Krita。MCP 进程使用 STDIO。Krita Python 插件仅监听 127.0.0.1，验证共享的 bearer token，并将每次 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 版本需要各自进行实时预检。

首次设置包含两个独立步骤：必须先安装并在 Krita 中启用本地桥接，然后通过市场插件或直接 MCP 配置连接 Codex。 codex plugin 命令不会在 Krita 中安装或启用任何内容。

Krita 必须包含 Python 脚本支持，通过实时兼容性检查，并且 PATH 中必须有 uv/uvx。 MCP 进程必须与 Krita 运行在同一台计算机上。本地 Codex CLI、IDE 和受支持的桌面客户端使用本地 MCP 配置；仅添加此 GitHub 仓库，托管的 ChatGPT 网页聊天无法通过这台计算机的 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 连接方式：市场插件或直接 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 技能，并通过 uvx 启动固定版本的 PyPI MCP 服务；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 桥接通过实时检查后，才使用此替代方案。使用 krita-codex-install codex-config 预览无需检出代码且精确锁定版本的 uvx Codex 配置块。只有在明确确认后才应用配置，然后重启 Codex，验证 krita_state 和 krita_preview，之后再开始常规工作。

安装和更新都不会关闭 Krita。如果经过身份验证的桥接正在运行，替换操作会在更改任何已安装文件之前被拒绝，且必须手动关闭 Krita。本地桥接端口被占用时，安装程序也会在开始替换前停止。

对于个人安装，请在 Linux 上使用用户级 ~/.codex/config.toml，或在 Windows 上使用 C:\Users\<you>\.codex\config.toml。这是推荐选项，因为这样所有本地 Codex 任务和 Git 工作树都能使用该服务。生成的配置块使用 uvx，不包含检出目录 cwd，并锁定到与已安装插件相同的精确发行版版本。安装程序只有在显示完整预览并收到明确确认后，才会修改该文件。不会覆盖未标记或存在冲突的 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 功能配置。运行中的插件会报告发行版、协议和 Krita 版本，而不会新增 MCP 工具。检查会创建一个临时文档，验证新建绘画图层、原生绘图、撤销／重做、事务性重设父级、直接获取 PNG 预览字节，以及在允许的根目录下生成临时 KRA／PNG 输出。检查完成后会恢复此前激活的文档并删除所有临时文件。

如果所有关键功能均通过，未知 Krita 版本也会被接受。缺少可选功能时会显示 limited 警告，并指出受影响的 MCP 工具；缺少投影、持久化、稳定图层树或文档生命周期 API 则属于关键问题。同一份结构化报告也可通过 krita_state 提供给 Codex，以便它避开不可用的操作。

功能与 Krita 限制

当前版本支持基于原生预设的绘画和形状、持久化文档与图层编辑、选区、颜色操作、KRA/PNG 输出，以及面向 Unity 的动画、图块集和命名区域包。预览和资源操作会直接向 MCP 调用方返回 PNG 图像。重新导出时会保留 Unity .meta 侧车文件，以确保生成的文件名稳定。

经过测试的 Krita 5.3.2.1 版本设有多项安全限制。其他版本会在运行时进行评估，报告的可用功能可能有所不同：

• 自由图层缩放、旋转、倾斜和裁切操作不是原生撤销命令。桥接程序会创建一个隐藏备份图层，并在 KRA 保存、关闭并重新打开之前阻止第二次直接变换。checkpoint_reopen=true 可自动完成这一往返过程。
• 每个打开的文档最多支持三个变换蒙版。在 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，后续调用会收到 BRIDGE_BUSY，直到 Krita 实际完成操作。

请尽可能缩小 allowed_roots 的范围，保留常规的版本化或手动 KRA 备份，并且不要将桥接程序超时视为取消操作。桥接程序仅在本地运行，并且只绑定到 127.0.0.1。

请参阅 Windows 安装、Linux 安装、Codex/MCP 兼容性、工具行为与限制、安全性和 GitHub 发行版。

许可证

基于 MIT License 发布。版权所有 (c) 2026 Nicklas Desens。