---

Aseprite MCP 将支持 MCP 的客户端如Codex，CluadeCode，DeepseekHarness等Agent与 Aseprite 连接起来，支持读取和编辑未保存画布、图片预览、撤销重做及可选基础动画，让你在同一文档中继续创作。同时保留 CLI 磁盘文件处理能力。

PyPI 安装包 · Release 扩展下载 · 问题反馈

Windows Aseprite 1.3+ 验证；Aseprite 需自行安装，不随项目分发。

快速开始

确保你已经安装了aseprite-扩展 然后可以使用你常用的ai agent工具输入以下内容：

请帮我安装这个项目https://github.com/greenlogs/aseprite-mcp-live的Aseprite MCP扩展，我的Aseprite已经安装好在[输入你的aseprite.exe 安装路径]，且已经安装了扩展并启用。

安装 uv（Windows）

在 PowerShell 中运行以下任意一种方式。

方式一：官方安装脚本

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

方式二：WinGet

winget install --id=astral-sh.uv -e

安装后重新打开终端，确认 uv 和附带的 uvx 可用：

uv --version
uvx --version

也可以从 uv 官方 Releases 下载对应 Windows 架构的压缩包，解压后将可执行文件所在目录加入 PATH。更多安装选项见 uv 官方安装说明。

本项目需要 Python 3.13+。可以让 uv 管理所需解释器：

uv python install 3.13

安装 Aseprite 扩展

两种服务启动方式都需要配套扩展：

1. 前往 GitHub Releases，下载与服务版本一致的 .aseprite-extension 文件。当前服务版本为 0.5.0。

2. 在 Aseprite 中打开 Edit → Preferences → Extensions → Add Extension，选择下载的扩展包，安装并启用。

   

   查看脚本状态：

   

   status 出现 Connected 状态表示扩展已成功连接服务

   

3. 重启 Aseprite，首次连接时按权限提示允许扩展使用本机 WebSocket。

注意事项：

• 1.若MCP连接正常但获取不到工具状态，尝试重启Agent客户端，尽量先让Aseprite先启动。
• 2.Agent工作时，尽量不要在画布上绘制，以免干扰实时协作。

扩展默认自动连接 127.0.0.1:8765。在 File → Scripts → MCP: Connect / Settings 中可查看状态、调整端口或断开连接，无需选择连接文件。

方式一：通过 uvx 运行（推荐）

直接从 PyPI 获取并运行，无需克隆仓库：

uvx --python 3.13 aseprite-mcp

以上命令启动 stdio MCP server，等待 MCP 客户端输入；终端保持等待属于正常行为。实际使用时，通常由 MCP 客户端按下列配置自动启动服务，无需另外开终端启动第二份。

MCP 客户端配置

以下适用于采用 mcpServers JSON 格式的客户端；其他客户端使用对应的 stdio 配置格式。

{
  "mcpServers": {
    "aseprite": {
      "command": "uvx",
      "args": ["--python", "3.13", "aseprite-mcp"],
      "env": {
        "ASEPRITE_MCP_TOOL_PROFILE": "all",
        "ASEPRITE_MCP_CAPABILITY_SETS": "animation"
      }
    }
  }
}

保存配置并重启客户端，然后打开 Aseprite。扩展与服务启动顺序不限，服务就绪后会自动连接。

方式二：本地构建与运行

需要 Git；也可以从仓库页面下载源码压缩包，解压后进入项目根目录。

git clone https://github.com/greenlogs/aseprite-mcp-live.git
cd aseprite-mcp-live
uv sync --locked --python 3.13
uv run --locked python scripts/build_release.py --out-dir dist

dist/ 中会生成 Python wheel、源码包、.aseprite-extension、锁定生产依赖清单和摘要文件。你可以安装对应版本的 Release 扩展，或使用本地生成的扩展包。

在项目根目录启动服务：

uv run --locked aseprite-mcp

由 MCP 客户端启动本地源码版本时，将配置替换为：

{
  "mcpServers": {
    "aseprite": {
      "command": "uv",
      "args": ["--directory", "{source-path}", "run", "--locked", "aseprite-mcp"],
      "env": {
        "ASEPRITE_MCP_TOOL_PROFILE": "all",
        "ASEPRITE_MCP_CAPABILITY_SETS": "animation"
      }
    }
  }
}

将 source-path 替换为源码目录的绝对路径如C:/path/to/aseprite-mcp-live。选择一种服务配置即可，同一端口只运行一份服务。

功能

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

Python MCP 服务通过 stdio 与客户端通信；Lua 扩展通过本机 WebSocket 连接服务，编辑 Aseprite 中的内存文档。实时编辑绑定明确的文档与修订，切换活动窗口不会改变操作目标。

可选配置

基础动画

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

{
  "ASEPRITE_MCP_CAPABILITY_SETS": "animation"
}

这会额外提供 apply_animation。支持追加末帧副本、删除帧、设置帧时长，以及创建、更新和删除标签。帧号从 1 开始，时长使用整数毫秒；每批动画操作支持一次撤销和重做，不自动保存。

工具范围与 Aseprite 路径

通过 ASEPRITE_MCP_TOOL_PROFILE 选择工具范围：

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

{
  "ASEPRITE_PATH": "{你的aseprite应用的绝对路径}",
  "ASEPRITE_MCP_TOOL_PROFILE": "all"
}

自定义端口

通过启动参数修改服务端口，例如：

uvx --python 3.13 aseprite-mcp==0.5.0 --port 8766

客户端配置中将 --port、8766 追加到 args，并在扩展设置中把 Port 改为 8766。本地源码运行同样支持 uv run --locked aseprite-mcp --port 8766。

使用范围

• 实时绘制以普通可编辑 RGB 图层为范围；非 RGB、锁定层、背景层、参考层和 Tilemap 等不支持的编辑会明确拒绝。调色板、特效、补间和 Tilemap 尚未迁移为实时能力。
• 编辑不会自动保存；保存为 .aseprite 或 .ase 时需明确指定路径，覆盖已有文件需显式设置覆盖参数。
• 撤销与重做针对文档最新历史，也可能涉及手动编辑。较大操作可能触发像素、复制或执行时间预算，需要缩小批次。
• 实时后端操作内存文档，CLI 后端操作磁盘文件。断线不会自动切换到 CLI；避免同时通过两种方式写入同一个磁盘文件。
• 服务仅监听本机回环地址。重连后需重新读取文档列表，不能复用旧会话和文档 ID。

故障排查

问题	处理方式
找不到 uv 或 uvx	安装后重开终端与客户端，或在客户端配置中使用可执行文件的绝对路径
扩展未连接	确认服务已由 MCP 客户端启动、扩展已启用、WebSocket 权限已允许，双方端口一致
端口被占用	关闭重复服务，或同时修改服务与扩展端口
版本不匹配	安装同版本的服务和扩展；可使用 aseprite-mcp==0.5.0 固定版本
找不到文档或修订冲突	重新读取文档列表与信息，使用当前会话和修订
预览图片未显示	确认客户端支持 MCP 图片内容，并缩小预览区域或缩放倍数

如仍有问题，请通过 GitHub Issues 提交软件版本、启动方式与错误信息。

致谢与许可

基于 diivi/aseprite-mcp 的工具与测试基础改造，保留上游 MIT 许可和版权，新增代码同样采用 MIT 许可。

本项目为第三方集成，与 Aseprite 官方无隶属关系。Aseprite 需自行准备，不随项目分发。