Allows controlling Krita via its LibKis API, providing MCP tools for observing canvas/document state, painting strokes, managing layers, brushes, colors, selections, filters, vector shapes, and document I/O, plus a closed-loop agent that iteratively reconstructs a target image.
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., "@Krita Canvas MCP run a closed-loop painting session to reconstruct the target image on the canvas"
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.
将 Krita 封装为 MCP（Model Context Protocol）工具集 + 闭环绘画 Agent：LLM 基于目标图像和画布快照逐笔预测动作，调用 Krita LibKis API 执行，迭代完成对目标图像的过程重建。
┌──────────────┐ MCP tools ┌──────────────────┐ JSON-RPC HTTP ┌─────────────┐
│ MCP 客户端 │ ←──────────→ │ external MCP │ ←─────────────→ │ Krita 插件 │
│ (Claude等) │ (stdio/http) │ server (src/) │ 127.0.0.1:5678 │ (plugin/) │
└──────────────┘ └────────┬─────────┘ └─────────────┘
│ 直接 bridge.call()
▼
┌──────────────────┐ ┌────────────────────┐
│ 闭环 Agent (loop) │→→│ 任意 OpenAI 兼容 VLM │
│ target+快照+热力图 │ │ (glm-4.6v/agnes…) │
└──────────────────┘ └────────────────────┘plugin/：Krita 内插件（LibKis 必须在主线程执行；HTTP 请求经队列由 QTimer 消费）
src/krita_canvas_mcp/：MCP 服务器（无状态工具转发）+ agent/ 闭环绘画代理（有状态：阶段/计划/颜色账本/动作历史）
scripts/：插件安装、全量工具测试脚本
tests/fixtures/：测试用目标图
# 复制到 Krita 的 pykrita 目录（Windows: %APPDATA%\krita\pykrita）
python scripts/install_plugin.py
# 开发模式（软链，修改 plugin/ 即时生效）
python scripts/install_plugin.py --link重启 Krita → 设置 → 配置 Krita → Python 插件管理器 → 勾选 Krita Canvas MCP → 再重启。
控制台出现 [krita-canvas-mcp] HTTP RPC listening on 127.0.0.1:5678 即成功。
在项目根目录创建 .env 文件：
VLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
VLM_API_KEY=your-api-key-here
VLM_MODEL=glm-4.6v-flash支持的环境变量覆盖：VLM_BASE_URL、VLM_API_KEY（兼容 GLM_API_KEY）、VLM_MODEL。
在 Krita 中按目标图尺寸新建文档（推荐 RGBA/U8，白底填充可选）。Agent 也支持自动创建（见下方 CLI 选项）。
python -m krita_canvas_mcp.agent --target <目标图路径> [--max-iterations 1000]可选参数：
参数 | 说明 | 默认值 |
| 最大迭代次数 | 1000 |
| VLM API Key（优先于 .env） | 从 .env 读取 |
| 模型名（优先于 .env） | 从 .env 读取 |
| OpenAI 兼容接口根地址（优先于 .env） | 从 .env 读取 |
| VLM 失败重试次数； | 无限 |
| 打印完整模型 API 返回（JSON，调试用） | — |
| 保存并打印发往模型的完整请求 JSON（图片落盘、JSON 内替换为相对路径，调试用） | — |
| 每步执行前暂停等待用户确认（回车继续 / q 退出） | — |
| 启用思考模式（Agnes 模型专用，提升推理能力） | — |
| 结果输出目录 |
|
| Krita 插件 RPC 地址 |
|
结果落盘到以时间戳命名的独立目录 outputs/<时间戳>/（每次运行一份，互不覆盖）：
final.png — 最终画布截图
summary.json — 会话指标、阶段分布、终止原因、缓存命中
action_history.jsonl — 逐轮动作记录
request_*.json / img_<hash>.png|jpg — 仅在 --raw-input 时生成：发往模型的完整请求 JSON（图片字段为相对路径）及抽出的图片；图片按内容哈希去重，逐轮相同的目标图只保存一份
# stdio 模式（Claude Desktop、Cursor 等 AI 编辑器接入）
python -m krita_canvas_mcp
# Streamable HTTP 模式（供 curl 调试）
python -m krita_canvas_mcp --transport streamable-http --port 8765Related MCP server: krita6-mcp
五阶段 O 计划 → A 草图 → B 线稿 → C 填色 → D 光影，显式 next_stage 切换（服务端校验：顺序推进 + 本阶段最少成功动作数，不满足拒绝并回显原因让模型重试）；plan 仅允许在 O 计划阶段输出，O→A 需 plan 已就绪
每轮一个动作：{"thought":"≤60字三段式","stage":"C","tool":"paint_path","params":{...},"color":"c3"}
硬约束 按阶段锁翻车：
A：禁止填充；笔刷 4~12px；仅允许灰/蓝色
B：禁止填充；笔刷 ≤3px；仅允许灰/蓝色
C：禁止半透明叠色（opacity < 0.9）
D：建议实色（opacity ≥ 0.9）
上下文装配 按字节稳定性分段以命中 LLM 前缀缓存：稳定文本前缀（stage/plan，置于图像之前）→ 目标图 + 画布快照 + 热力图（C/D 阶段）→ 变化文本后缀（iter 计数 + 颜色账本（c1..cN）+ 近 5 步动作 + 区域进度 + 采样/反馈）
缓存遥测 每轮读取响应 usage 的 prompt_cache_hit_tokens / prompt_cache_miss_tokens，逐轮打印并汇总进 outputs/<时间戳>/summary.json 的 prompt_cache 字段
终止条件 LLM 自报 done / 达到迭代上限（默认 1000 轮）
LLM 的 color 字段支持 cN（账本编号，按使用频率降序）或 #RRGGBB，执行前自动转为 set_colors(foreground)
所有工具定义见 src/krita_canvas_mcp/resources/mcp-tools-schema.json。
工具 | 说明 |
| 获取当前文档元信息（尺寸、色彩模型、色深、配置文件、分辨率、是否已修改） |
| 拍摄画布合成结果快照（PNG base64 + 哈希） |
| 读取单个图层内容（非合成，PNG base64） |
| 列出图层全部颜色/Alpha 通道（名称/可见性/位宽/边界） |
| 读取单通道灰度图（PNG base64） |
| 当前选区输出为灰度蒙版 PNG（0~255 selectedness） |
| 读回视图状态（缩放/旋转/镜像）与当前绘画参数 |
| 枚举 Krita 打开的所有文档 |
工具 | 说明 |
| 两点直线（带首尾压感），适合轮廓/排线 |
| 沿折线/贝塞尔路径绘制自由笔画（闭环主通道） |
| 椭圆/矩形/多边形色块（可选描边+填充） |
| 将像素补丁（RGBA PNG/base64）直接写入图层指定区域 |
| 检查图层能否被当前笔刷绘制（PAINT/VECTOR/CLONE/UNPAINTABLE） |
| 阻塞至所有后台笔刷任务完成并刷新投影合成 |
工具 | 说明 |
| 设置前景/背景色（ |
| 批量设置画笔参数：size/opacity/flow/rotation/pattern_size |
| 按名称激活笔刷预设 |
| 枚举可用资源：preset/brush/pattern/gradient/palette/workspace |
| 设置画笔混合模式（view 级）或图层混合模式（node 级） |
| 橡皮模式/锁定透明像素/禁用压感开关 |
| 从目标图/画布/图层采样颜色，返回多种色彩空间表示（srgb_hex/srgb_255/lab/hsv） |
| 撤销上一步（支持多步） |
| 重做被撤销的操作 |
工具 | 说明 |
| 获取图层树（名称/类型/id/可见性/透明度/混合模式/父子关系） |
| 创建图层/蒙版并挂到指定父节点 |
| 创建整层纯色/图案填充层（快速铺底） |
| 批量设置图层属性：name/visible/locked/opacity/blending_mode/alpha_locked/inherit_alpha |
| 节点操作：remove/duplicate/merge_down/move/set_active/reorder |
工具 | 说明 |
| 将灰度补丁（PNG/base64）写入图层的单个通道 |
| 灰度 PNG 蒙版写入并激活为文档选区（0~255 selectedness） |
| 选区操作：select_rect/select_all/clear/invert/feather/grow/shrink/smooth/border/erode/dilate/move/resize |
工具 | 说明 |
| 把 SVG 字符串加入矢量图层（坐标单位 pt） |
| 枚举矢量图层 top-level 形状（名称/bbox/变换/选中态） |
| 矢量形状操作：remove/select/deselect/set_position/set_transform/set_zindex/group |
| 整层或单形状导出为 SVG 字符串 |
工具 | 说明 |
| 对图层应用滤镜； |
| 读取滤镜默认配置模板（属性名与默认值） |
| 整幅文档变换：scale/rotate/shear/crop/resize |
| 图层几何变换：scale/rotate/shear/crop |
工具 | 说明 |
| 新建画布（含指定色彩模型/色深/ICC/分辨率） |
| 打开图像文件并展示 |
| 按 document_id 关闭文档 |
| 保存/另存/导出（PNG/JPEG/KRA，支持节点级导出） |
| Krita 版本/批处理模式/活动文档状态 |
| 触发任意 Krita 内建动作（ |
| 读写插件持久化设置（kritarc） |
| 设置视图：zoom/rotation/mirror/center_to/reset_view |
工具 | 说明 |
| 设置当前会话的目标图像（可选在活动画布顶层叠加锁定参考层） |
| 获取目标图像 PNG（base64），支持 original/gray/edge/palette_quantized 变体 |
| 校验画布与目标图尺寸/色彩模型是否匹配 |
| 计算画布与目标图的差异，返回标量指标（mae/rmse/psnr/ssim/ΔE）+ 热点 + 可选热力图 |
| 统计画布相对基线的推进：已覆盖/未触及/上轮变化，返回区域级覆盖度与停滞检测 |
| 拉取最近绘画动作记录（stats_only/summary/full 三种格式） |
| 读取当前绘画会话的完整状态（目标图/阶段/迭代计数/规划/颜色账本/停滞检测） |
| 终止当前会话，清理缓存与状态（可选保留画布/保存半成品快照） |
| 从文档合成画面量化抽取主色（kmeans/median_cut），可写入调色板资源 |
| 读取指定调色板的色值列表 |
| 当前画布快照哈希（连调两次可判断画布是否变化） |
每次迭代计算目标图与画布的以下指标：
指标 | 说明 |
| 平均绝对误差（RGB 空间） |
| 均方根误差 |
| 峰值信噪比（dB） |
| 结构相似度（8×8 分块均值） |
| CIELAB ΔE 均值 / 95 分位 |
| 匹配度：前景像素中 ΔE < 6 的占比 |
| 已绘占比：画布上相对白底已落笔的像素占比 |
A/B 阶段以 painted_pct 为主指标（结构推进）；C/D 阶段以 covered_pct 为主指标（颜色贴合）
白背景与白画布天然 ΔE≈0，计入匹配度会虚高——因此所有统计仅覆盖目标前景像素
LLM 自报 done（llm_done）
达到迭代上限（max_iter，默认 1000）
VLM（模型 API）连续失败 3 次（vlm_failed，每轮内部先指数退避重试）
--confirm 模式下用户输入 q（user_quit）
注：工具执行失败（KritaError）不中断，仅回显错误让模型重试。
每次调用 set_colors 登记颜色，按使用频率降序编号为 c1 / c2 / …。LLM 可在后续动作中通过 color: "c3" 引用，避免重复输入 #RRGGBB。C/D 阶段禁止引用 c1/c2（通常残留 A/B 草稿灰）。
兼容任意 OpenAI Chat Completions 接口：
默认调用 VLM_BASE_URL + /chat/completions
支持 enable_thinking 参数（模型名含 agnes 时自动注入 chat_template_kwargs.enable_thinking=true）
调用失败时按指数退避重试（3s → 6s → 12s → … → 上限 60s）；重试耗尽抛 VLMError，连续 3 次失败 Agent 强制终止
# 前置：Krita 已启动且插件启用（127.0.0.1:5678/rpc）
python scripts/test_all_tools.py
python scripts/test_all_tools.py --keep-fixtures # 保留测试文档，便于排查
python scripts/test_all_tools.py --target tests/fixtures/target_512.png测试覆盖 59 个工具，分为 12 个阶段：
观测：文档信息、画布快照、节点树、视图状态、通道/选区采样
环境搭建：多层级节点创建（paintlayer/grouplayer/vectorlayer/filelayer/fill layer）
绘画链：直线/路径/形状/像素写入、通道像素、调色板提取、差异度量
撤销/同步/历史：undo/redo、动作历史三种格式、session_state
选区/像素：选区操作全链路（select_rect/invert/feather/grow/clear/set_selection_pixels）
配置读回：笔刷参数、前景色、Alpha 锁定、图层混合模式
图层管理：duplicate/move/reorder/merge_down/remove/transform
矢量：SVG 添加/查询/操作/导出
滤镜/变换：滤镜列表/配置/应用（普通层与非破坏层）、文档变换（resize/rotate/scale）
会话/IO：open/save/close document、settings 读写、view_state 设置
阶段硬约束全部用例（A 禁填充/禁实色、B 粗笔、C 透明叠色）
plan → paint_path → done 主循环；违规 → 拒绝 → 修正恢复路径
差异度量（mae/rmse/psnr/ssim/ΔE/covered_pct/热力图）
颜色账本 cN 解析
LLM 输出 JSON 容错解析（围栏剥离、双层嵌套 bbox、字典坐标兼容）
krita-canvas-mcp/
├── plugin/krita_canvas_mcp/ # Krita 内插件（LibKis 操作）
├── src/krita_canvas_mcp/
│ ├── __main__.py # 入口（stdio/HTTP）
│ ├── server.py # MCP Server 装配
│ ├── bridge.py # HTTP 桥接（→ Krita 插件）
│ ├── envelope.py # 响应信封（ok/data / ok:false+err）
│ ├── errors.py # 错误码枚举
│ ├── prompts.py # 系统提示词（单一来源）
│ ├── tools/ # 工具注册模块
│ │ ├── observe.py / paint.py / brush.py / node.py
│ │ ├── imaging.py / vector.py / fx.py / document_io.py / session.py
│ └── agent/ # 闭环 Agent
│ ├── __main__.py / loop.py # CLI 入口 + 主循环
│ ├── context_builder.py # 上下文装配 + LLM 输出解析
│ ├── session_state.py # CanvasMetrics / ColorLedger / SessionState
│ ├── stage_rules.py # 阶段硬约束 + 切换校验
│ └── vlm_client.py # 多模态 VLM 客户端
├── scripts/
│ ├── install_plugin.py # 插件部署脚本
│ └── test_all_tools.py # 59 工具全量测试
└── tests/fixtures/
└── target_512.png # 512×512 目标图变量 | 说明 |
| VLM OpenAI 兼容接口根地址（如 |
| API Key（本地免 key 服务可留空 |
| 兼容别名， |
| 模型名（如 |
| 外部系统提示词文件路径，覆盖内置提示词（两侧同效） |
| 显式指定 .env 文件路径 |
项目进度：当前项目未完成，效果如图所示：
Krita 版本：插件基于 Krita Python API（from krita import Extension）与 LibKis 交互，已在 Krita 6.0.4 验证
LibKis 主线程限制：所有 LibKis 调用必须在线程安全队列中由 Krita 主线程执行；MCP 工具只发 HTTP 请求
画布不做缩放：闭环 Agent 直接以画布真实像素尺寸工作（target/快照/热力图与画布严格同尺寸），模型输出的坐标即真实坐标，无需换算
颜色管理：AI 绘制的颜色不可逆——undo 仅回退动作，不恢复被覆盖的历史颜色；建议在关键阶段前 save_document
Windows 兼容性：.desktop 软链在 Windows 需管理员权限或开发者模式；install_plugin.py --link 失败时自动回退复制模式
This server cannot be deployed
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
MCP server for progressive tool usage at any scale (see https://klavis.ai)