Krita Illustration MCP

让 AI 大模型通过 MCP 直接控制本机 Krita。模型查看 krita_preview 返回的真实画布，决定下一步文档、图层和绘制操作；Krita Bridge 在主线程执行，所以变化会直接显示在 Krita 中。

复杂人物插画优先使用混合流程：客户端生成参考图 → 客户端生图工具转换线稿 → MCP 导入独立图层 → Krita 局部修正和导出。生成与原生笔画必须明确区分，不把导入 PNG 冒充逐笔绘制或自动语义分层。服务本身默认不调用外部生图 API、不读取厂商密钥；GPT/Gemini 仍只保留未配置的扩展接口。

当前能力

• 创建透明画布和独立图层。

• krita_image 检查 PNG 尺寸/哈希，并以来源标记导入新图层；保留图片副本，重复请求不重复导入。

• 查询文档/图层状态并返回真实 PNG 预览。

• 定义、裁剪、预览区域并创建/扩展/羽化蒙版。

• 用 krita_inpaint 将客户端或已配置 provider 生成的局部 PNG 按 Mask 应用为新图层。

• 创建 KRA checkpoint，恢复为新文档。

• 安全保存 KRA 和导出 PNG。

• 对关键原生修改使用持久化 request_id 去重。

• 用 krita_paint 调用 Krita Brush Engine 批量绘制有压力信息的笔画。

• 用 krita_draw 绘制直线、折线、贝塞尔曲线、矩形、椭圆和可填充多边形。

• 用 krita_illustration 持久化草稿、线稿、底色、阴影、高光、终检和导出阶段，未预览不能推进。

原生图元、局部清除、预览和保存已经通过牡丹绘制实机验证；人物逐曲线重画成本较高，因此不再作为复杂插画的推荐主流程。图片入口复用现有 Bridge import_image，本次仅需重新加载 MCP 服务，不必重新安装 Bridge。

Related MCP server: GIMP MCP

目录

src/krita_workbench/
  domain/             纯数据与规则
  application/        Krita 原生控制用例
  contracts/          MCP 与 Bridge 共享契约
  adapters/krita/     本机 Bridge 客户端
  adapters/storage/   job、region、checkpoint 持久化
  native/             Krita 插件与主线程操作
  transport/mcp.py    STDIO MCP 工具
docs/                 架构、契约、开发计划、启动说明
dist/                 Krita 插件 ZIP

安装 Krita Bridge

在 Krita 中选择“工具 → 脚本 → 导入 Python 插件”，导入：

D:/krita-mcp/dist/krita_workbench_bridge-20260905.zip

启用插件并重启 Krita。详细步骤见 native-bridge.md。

使用 uv 启动 MCP

先确保 D:/krita-mcp/config.local.json 与其中引用的 Bridge 配置存在，然后在 PowerShell 执行：

cd D:/krita-mcp
uv run python -m krita_workbench --config D:/krita-mcp/config.local.json --check-config
uv run python -m krita_workbench --config D:/krita-mcp/config.local.json

第二条命令启动 STDIO MCP 服务，等待 MCP 客户端连接；它不是交互式命令行。

可使用 config/mcp.example.json 配置客户端直接启动该服务。

推荐调用顺序

复杂插画采用以下流程，参数示例见 混合绘图流程：

1. 客户端生图并确认参考图，再以参考图为编辑输入生成干净线稿。

2. 将 PNG 复制到 D:/krita-mcp/artifacts/，不扩大 Bridge 的 allowed roots。

3. krita_image(action="inspect") 获取真实尺寸，再新建匹配画布。

4. 分别导入 reference 和 lineart；隐藏 reference，预览检查线稿。

5. 对手、眼睛、头发或褶皱定义 region，创建/扩展/羽化 Mask。

6. 用客户端生成与 region 尺寸完全一致的修复 PNG，调用 krita_inpaint；结果会按 Mask 变成透明补丁并新增图层。

7. 预览修复结果，在新的修正图层用 krita_paint/krita_draw 补线；危险修改前 checkpoint。

8. 最终预览后 krita_save_export；导入的是栅格层，不是自动拆出的头发/皮肤/服装层。

需要全程原生绘制时，原有流程仍可选：

1. krita_capabilities

2. krita_state

3. krita_document 创建透明画布和目标图层

4. krita_illustration(action="start") 记录文档和五个目标图层

5. 通过 krita_paint/krita_draw 分批写入当前阶段图层

6. 每个主要阶段后 krita_preview，再用 krita_illustration(action="advance") 记录通过

7. 高风险修改前 krita_history(action="checkpoint")

8. 完成后 krita_save_export，记录 export 阶段并完成会话

krita_capabilities.external_image_generation 会显示保留的 gpt、gemini 槽位。默认 enabled=false、configured=false；只有未来显式实现并注入 provider adapter 后才会启用。

验证

测试只使用 mocks 和临时目录，不访问真实 Krita：

$env:PYTHONPATH='D:/krita-mcp/src;D:/krita-mcp'
D:/krita-mcp/.venv/Scripts/python.exe -m unittest discover -s tests -t . -v

离线测试通过不等于真实 Krita 绘制验收。每个新增原生能力必须另做运行中 Krita 的可见操作和 preview 检查。