内容
# aseprite-live-mcp
[](https://pypi.org/project/aseprite-live-mcp/)
**让 AI 代理在您的实时 Aseprite 编辑器中绘图 — 每次编辑一个命名撤销 — 使用 Unity-first、游戏开发工具集。**
一个开源的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，适用于 [Aseprite](https://www.aseprite.org/)。它驱动您的**正在运行的编辑器**（所有打开的文档、未保存的状态、每次编辑一个撤销）*和*运行**无头**（`aseprite --batch`）针对磁盘上的文件 — **77 种类型工具**，来自一个服务器，包括一次性**Unity 精灵表 + `.meta` 导出**（命名切片携带每个切片的枢轴）、项目约定**艺术质量扫描**和**等距绘图基元**，我们尚未在另一个 Aseprite MCP 中找到。它还公开了 **MCP 提示** — 有指导的单次调用艺术工作流，我们尚未在另一个 Aseprite MCP 中看到 — 以及 **MCP 资源**，它们读取您的实时编辑器的打开文档、活动调色板和上一次质量/导出报告（一个实时状态资源集，仅适用于实时桥接）。
## 查看实际操作
这些都是 AI 代理通过 MCP 驱动的**实时** 64×64 Aseprite 画布 — 每次步骤一个命名撤销。
<table>
<tr>
<td align="center"><img src="docs/demo.gif" width="240" alt="等距机器构建"><br><sub><b>等距基元</b><br>等距盒 → 凹陷端口 → 油箱 → 大纲</sub></td>
<td align="center"><img src="docs/demo-drawing.gif" width="240" alt="绘图套件"><br><sub><b>绘图套件</b><br>矩形 · 抖动渐变 · 椭圆 · 圆圈 · 抖动 · 大纲</sub></td>
<td align="center"><img src="docs/demo-shading.gif" width="240" alt="调色板斜坡着色"><br><sub><b>斜坡着色</b><br>平面填充 → 体积，沿着手动排序的调色板</sub></td>
</tr>
</table>
## 安装
**推荐 — 一个命令（无需克隆）：**
```bash
uvx aseprite-live-mcp # 或：pipx run aseprite-live-mcp
```
**从源代码：**
```bash
git clone https://github.com/oaktreegames/aseprite-live-mcp
cd aseprite-live-mcp
pip install -e .
```
需要 **Python 3.10+** 和 **Aseprite 1.3+**。这就是无头模式所需要的；实时编辑器需要一个额外的步骤（如下）。
## 快速入门 — 无头模式（2 分钟，无编辑器打开）
将服务器添加到您的 MCP 客户端（Claude Code、Claude Desktop、Cursor、...）：
```jsonc
{
"mcpServers": {
"aseprite-live": {
"command": "uvx",
"args": ["aseprite-live-mcp"],
"env": {
"ASEPRITE_MCP_BACKEND": "headless",
"ASEPRITE_PATH": "C:/Program Files/Aseprite/Aseprite.exe"
}
}
}
}
```
设置 `ASEPRITE_PATH` 为您的 Aseprite 可执行文件（如果省略，则在常见安装中自动检测）。在无头模式下，工具接受一个 `file` 参数 — `.aseprite` 要操作的 文件。要求您的代理运行 `status` 以确认连接。
## 快速入门 — 实时编辑器（驱动您的打开的画布）
实时后端编辑您的**正在运行的** Aseprite，每次编辑一个撤销步骤。
1. **将桥接脚本安装到 Aseprite** — 在 Aseprite 中，`文件 → 脚本 → 打开脚本文件夹`，并复制 [`aseprite_client/claude-bridge.lua`](aseprite_client/claude-bridge.lua) 到其中。重启 Aseprite（或 `文件 → 脚本 → 重新扫描脚本文件夹`）。
2. **启动中继：** `python bridge/relay_server.py`（需要 `pip install websockets`）。
3. **连接：** 在 Aseprite 中，`文件 → 脚本 → claude-bridge`，并授予脚本信任时请求的权限。面板显示 **"连接到 Claude"**，实时活动和暂停切换。
4. **切换后端** 到 `live` 在您的 MCP 配置中（`"ASEPRITE_MCP_BACKEND": "live"`）。
现在工具对您的活动文档起作用；观察编辑出现并按 Ctrl-Z 撤销每个编辑。参见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 了解其工作原理。
## 您可以用它做什么
- *"创建一个 32×32 精灵，绘制一个红色圆圈，并将其导出为 icon.png。"*
- *"测量 player.aseprite 的透明填充并告诉我它是否居中。"*
- *"将 machines.aseprite 导出为 Unity 精灵表，单位为 16 像素。"* → 将表格和预切片的 `.meta` 直接放入您的 Unity 项目中。
- *"为 1×1 机器底座绘制一个等距盒，并在其前面添加一个凹陷端口。"*
- *"对该精灵运行质量扫描：它必须为 64×64，≤ 16 种颜色，并网格对齐。"*
- *"从 concept.png 中提取一个 16 色调色板，并使我的精灵与其对齐。"*
- *"切片此图集，设置每个切片的枢轴，并将其导出到 Unity 中，并将枢轴烘焙到其中。"*
使用 `python tests/smoke_headless.py` 检查整个表面：该测试运行所有 77 个工具（以及资源和提示）端到端，针对一个临时精灵（`pip install -e ".[dev]"` 然后 `pytest` 进行单元测试和无头测试套件）。
## 它在业界的位置（诚实的定位）
已经有不错的 Aseprite MCP 服务器存在。这个项目 **不是第一个**，也不声称自己是第一个。它声称并可以证明的是：
| 功能 | 行业现状 | 该项目 |
|---|---|---|
| 绘制 / 图层 / 帧 / 调色板 / 导出，加上渐变、抖动、大纲、颜色替换、量化、斜坡、从图像创建调色板 | 被头部领导者很好地覆盖（diivi ~104 工具，pixel-mcp，ext-sakamoro） | **对齐** — 一个干净的、类型化的、精选的界面 |
| 调色板约束着色，单元格补间 | 已在其他地方发布（pixel-mcp `apply_shading`，diivi 补间） | 对齐 |
| Godot `.tres` SpriteFrames 导出 | 已发布（商业 Aseprite MCP Pro） | 不在范围内 — 已经解决 |
| **Unity `.meta` 精灵导出为一步操作 — 帧（统一枢轴/对齐预设） *或* 命名切片（每个切片都有自己的内置枢轴）** | **未占用** — 每个 Aseprite→Unity 路径都是一个单独的引擎端导入器，没有一个导出枢轴 | **差异化** ✅ |
| **艺术质量扫描，包括透明贴纸填充测量** | 没有一个 MCP 将其作为扫描；我们在调查的 MCP 或 lint 工具中没有找到填充测量 | **差异化** ✅ |
| **等距绘图基元** （2:1 等距盒/圆柱体，自动面着色，凹陷端口） | 我们调查的 Aseprite MCP 没有一个具有它们 — 都是平面画布 | **差异化** ✅ |
| **MCP 资源，用于实时编辑器状态** （打开/未保存的文档，活动调色板，最后的 QA + 导出报告） | 只有一个初始服务器公开任何资源，而且是无头的 — 没有实时的读取内容 | **差异化** ✅ |
| **MCP 提示 — 有指导的一次调用艺术工作流** （`unity_qa_gate`，`iso_building_to_spec`，...） | 我们发现的 Aseprite MCP 没有一个公开正式的协议提示（一些提供指南字符串或外部文档） | **差异化** ✅ |
| 实时编辑器，具有 **每个编辑一个命名的 `app.transaction` 撤销** | 实时 GUI 存在（Pro 商业；Dizzd/Shexiaoyun OSS，初始）；每个编辑的交易纪律不是一个声明的保证 | **组合** 中的可辩护性（撤销 + 实时资源 + 实时文档的 QA） |
我们不竞争原始工具数量（领导者提供 100+）。宣传的是 **精选的、Unity-first 和 QA-gated**，具有 **MCP-native 集成层** — 有指导的工作流提示（我们尚未看到另一个 Aseprite MCP 发布）和实时状态资源（仅适用于实时桥接）。
## 工具（77）
- **检查** — `status`，`get_sprite_info`，`get_pixel`，`get_pixels`（用于 AI 反馈环的复合读取），`get_color_stats`（直方图）
- **画布/图层/帧/单元格** — `create_sprite`；`add_layer`/`delete_layer`/`rename_layer`/`set_layer_visibility`/`set_layer_opacity`/`set_layer_blend_mode`/`duplicate_layer`/`merge_layer_down`/`move_layer`/`import_image_as_layer`/`flatten_sprite`；`add_frame`/`duplicate_frame`/`delete_frame`/`set_frame_duration`；`clear_cel`/`set_cel_position`/`set_cel_opacity`
- **标签** — `create_tag`，`list_tags`，`delete_tag`
- **绘制** — `draw_rectangle`，`draw_line`，`draw_circle`，`draw_ellipse`，`draw_gradient`（可选抖动），`apply_dither`（有序 Bayer），`add_outline`，`fill_area`
- **调色板/颜色** — `get_palette`，`set_palette_color`，`add_palette_color`，`set_palette`，`apply_preset_palette`（gameboy/pico8/cga），`generate_color_ramp`（色调偏移），`extract_palette_from_image`（中位切割）；`replace_color`，`quantize_to_palette`，`adjust_hsl`
- **着色** — `apply_shading`，`palette_ramp_walk`（索引邻接斜坡着色）
- **选择/变换** — `select_rectangle`/`select_all`/`deselect`；`flip_sprite`/`rotate_sprite`/`resize_sprite`/`crop_sprite`
- **切片** — `create_slice`，`set_slice_pivot`，`set_slice_center`（9-patch），`list_slices`，`delete_slice`
- **动画** — `tween_frames`，`smear_frame`
- **等距** — `draw_iso_box`，`draw_iso_cylinder`，`fill_polygon`，`iso_recessed_panel`（2:1 等距基元，具有自动顶部/左侧/右侧面着色）
- **导出** — `export_sprite`（诚实的帧拆分报告），`export_spritesheet`（+ JSON 图集），`export_unity_sprite`（帧），`export_unity_slices`（命名切片，每个切片的枢轴）
- **批处理** （整个文件夹，无头，非破坏性）— `batch_export`，`batch_resize`，`batch_apply_palette`
- **编辑器** — `undo`，`redo` · **高级** — `run_lua`（ guarded escape hatch）
- **艺术质量** — `measure_padding`，`qa_sweep`
每个工具都使用准确的 MCP 注释进行类型化（`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`）；变异工具包装在一个命名的 `app.transaction` 中，因此每个编辑都恰好是一个撤销步骤（编辑器显示“撤销 <标签>”）。质量和 Unity 导出工具还声明了一个 `outputSchema` 并返回 `structuredContent`。构建在官方 MCP Python SDK 的 `FastMCP`、stdio 传输上，针对稳定的 **2025-11-25** 规范。
## 资源
无需调用工具即可读取实时编辑器状态 — 由实时桥接启用：
- `aseprite://sprite/active` — 大小、颜色模式、图层/帧/标签名称的活动文档
- `aseprite://palette/active` — 活动调色板为十六进制
- `aseprite://docs` — 每个打开的文档，包括未保存/未标题的标签页
- `aseprite://qa/last` — 最近的 `qa_sweep` / `measure_padding` 结果
- `aseprite://export/last` — 最近的 Unity 导出（写入的文件 + 精灵清单）
## 提示（有指导的工作流）
一次性“技能”，将工具链成完成的艺术任务：
- `unity_qa_gate` — 运行准备发货的 QA 门户，然后导出 Unity 表格 + `.meta`
- `iso_building_to_spec` — 根据规格构建 2:1 等距建筑
- `shade_along_ramp` — 通过行走其手动排序的调色板斜坡来着色精灵
- `autoslice_to_unity` — 多帧精灵 → 准备好 Unity 导入的表格 + 预切片 `.meta`
- `concept_to_placeholder` — 外部概念图像 → 正确填充，调色板内占位符
## 安全
中继在 Aseprite 内执行 Lua — 将其视为本地代码执行。它仅绑定到 `127.0.0.1`，每次编辑都是一个撤销步骤。完整威胁模型： [`SECURITY.md`](SECURITY.md)。
## 贡献
欢迎提出问题和 PR — 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。在提交前运行 `pytest` 和 `python tests/smoke_headless.py`。
## 许可证
MIT — 参见 [`LICENSE`](LICENSE)。© 2026 Kyle Ocheltree / OakTree Games.
<!-- mcp-name: io.github.oaktreegames/aseprite-live-mcp -->
<!-- 上一行是 MCP 注册表 PyPI 所有权标记（在 PyPI 描述中发布）。它必须与 server.json 中的"name"匹配。不要删除。 -->
