---

Aseprite MCP 将支持 MCP 的 AI 客户端与 Aseprite 连接起来。你可以用自然语言描述修改，让 AI 直接编辑当前文档并查看图片反馈，再接着手动创作——包括尚未保存的画布。

基于 diivi/aseprite-mcp 改造，新增 Lua 实时扩展，同时保留上游 CLI 文件工具。

当前版本为 0.4.1 TestPyPI 测试版。已在 Windows + Aseprite 1.3.7 / API 28 完成真实验证，最近一次完整回归为 208 项通过。macOS、Linux 和其他 Aseprite 版本尚待验证。

快速开始

1. 准备服务与扩展

需要自行安装的 Aseprite 1.3.7 / API 28、Python 3.13+、uv 和支持 stdio 的 MCP 客户端。

获取本项目源码后，在项目根目录运行：

uv sync --locked --python 3.13
uv run --locked python scripts/build_release.py --out-dir dist

2. 安装 Aseprite 扩展

在 Edit → Preferences → Extensions → Add Extension 中选择生成的 dist/aseprite-mcp-live-0.4.1.aseprite-extension，安装并启用，然后重启 Aseprite。

3. 配置 MCP 客户端

下面是采用 mcpServers 格式的客户端配置示例。将 C:/path/to/aseprite-mcp 替换为项目的绝对路径；其他客户端使用对应的 stdio 配置格式。

{
  "mcpServers": {
    "aseprite": {
      "command": "uv",
      "args": [
        "--directory", "C:/path/to/aseprite-mcp",
        "run", "--locked", "aseprite-mcp"
      ],
      "env": {
        "ASEPRITE_MCP_TOOL_PROFILE": "core"
      }
    }
  }
}

重启客户端，打开 Aseprite，按首次权限提示允许扩展使用本机 WebSocket。默认自动连接 127.0.0.1:8765，无需选择连接文件。

试着对 AI 说：“查看当前打开的画布，告诉我有哪些图层，并显示预览。”

独立安装、端口设置与连接诊断

• 不依赖源码目录的 wheel 安装、ASEPRITE_PATH 配置和手动扩展安装见 Windows 安装说明。
• 服务由 MCP 客户端启动；同一端口只运行一份服务。客户端找不到 uv 时，用 Get-Command uv 查询其绝对路径。
• 在 File → Scripts → MCP: Connect / Settings 查看连接状态或修改端口。服务参数 --port 必须与扩展设置一致。
• 升级时同时更新服务和扩展；详细步骤见安装与升级。

功能

功能	你可以做什么
实时协作	读取、编辑已经打开的文档，包括未保存画布，继续与 AI 交替创作
像素与图层	新建 RGB 画布、添加普通图层、调整不透明度、批量绘制像素和矩形
图片反馈	将画布预览作为 PNG 图片直接返回给支持图片内容的 MCP 客户端
撤销与重做	一个编辑批次对应一次撤销，可使用 Aseprite 原生历史继续调整
基础动画（可选）	追加或删除帧、设置帧时长、创建和管理动画标签
CLI 文件工具	单独启用磁盘文件处理，使用已保留的上游工具进行批处理
自动连接	扩展在软件启动后等待服务，服务重启后自动重新连接

工作方式

系统由两个组件组成：

1. Python MCP 服务：与 AI 客户端通过 stdio 通信，处理工具调用并返回文字或图片。
2. Aseprite Lua 扩展：通过本机 WebSocket 连接服务，读取和修改编辑器中的内存文档。

实时编辑绑定明确的文档和修订；切换活动窗口不会把修改转移到其他画布。CLI 工具操作磁盘文件，实时连接失败会返回错误，不会自动改用 CLI。

使用示例

先在 Aseprite 中打开或新建画布，然后描述目标：

示例指令	用途
“读取当前文档的尺寸、图层和帧信息，先给我预览。”	了解画布
“创建一个 32×32 的 RGB 画布，用像素和矩形画一把小剑。”	从空白开始绘制
“在这个文档中新建高光图层，添加几处浅色像素，完成后预览。”	分层修改
“撤销刚才那一批修改，再显示结果。”	检查与调整
“追加两帧，将前三帧设为 180 毫秒，并创建 walk 标签。”	基础动画，需先启用

编辑不会自动保存。需要落盘时，明确要求保存为 .aseprite 或 .ase 文件；覆盖已有文件需要显式设置覆盖参数。撤销和重做针对文档最新历史，也可能涉及你手动完成的编辑。

启用基础动画

在 MCP 客户端的 env 中增加以下配置，并重启服务：

{
  "ASEPRITE_MCP_CAPABILITY_SETS": "animation"
}

配套 0.4.1 服务和扩展会额外提供 apply_animation。追加帧复制末帧，帧号从 1 开始；详细范围与参数见能力清单。

工具配置

通过客户端环境变量 ASEPRITE_MCP_TOOL_PROFILE 选择：

值	工具范围
core（默认）	9 个实时核心入口；启用动画后为 10 个
cli	116 个磁盘文件工具；通过 ASEPRITE_PATH 配置 Aseprite，不建立实时连接
all	实时与 CLI 合计 125 个；启用动画后为 126 个

CLI 工具的数量不代表实时功能数量。完整配置见安装说明，参数上限见 .env.example。

当前边界

• 实时绘制以普通可编辑 RGB 图层为范围；非 RGB、锁定层、背景层、参考层和 Tilemap 等不支持的编辑会明确拒绝。
• 调色板、特效、补间和 Tilemap 尚未迁移为实时能力。
• 较大的操作可能触发像素、复制或执行时间预算，需缩小批次；不能确定写入结果时，先重新读取状态再操作。
• 服务仅监听本机回环地址。CLI 修改文件与编辑器内存修改分开使用，避免同时写入同一磁盘文件。

故障排查

问题	建议
扩展未连接	确认 MCP 服务已由客户端启动、扩展已启用，双方端口一致
端口被占用	结束重复服务，或同时修改服务 --port 与扩展端口
找不到文档或修订冲突	重新读取文档列表与文档信息；重连后旧会话和文档 ID 失效
没有显示预览图片	确认客户端支持 MCP 图片内容，并缩小预览区域或缩放倍数

更多错误与恢复步骤见故障排查。

文档与贡献

安装与使用 · 兼容能力 · 测试说明 · 构建与发布 · 参与贡献

开发维护入口：执行计划、项目结构和架构说明。详细文档目前以中文提供。

致谢与许可

感谢 diivi/aseprite-mcp 提供的上游工具与测试基础；实际导入版本和改造记录见第三方来源。

本项目采用 MIT 许可，保留上游版权。Aseprite 需自行准备，不随项目分发。本项目为第三方集成，与 Aseprite 官方无隶属关系。