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.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",
      // 因Codex多会话进程原因，需要共享模式的客户端，添加 --shared 参数
      "args": ["--python", "3.13", "aseprite-mcp", "--shared"],
      "env": {
        // 默认启用核心工具模式core，其他可选值为all，cli模式
        "ASEPRITE_MCP_TOOL_PROFILE": "core",
        // 为core模式启用动画能力
        "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

在项目根目录启动服务：

uv run --locked aseprite-mcp

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

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

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

功能

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

可选配置

可拓展工具

详细工具列表：工具列表

选择项目合适的功能防止上下文干扰，在客户端配置的 env 中增加以下项，并重启服务：

{
  // 启动动画绘制
  "ASEPRITE_MCP_CAPABILITY_SETS": "animation"
}

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

工具范围与 Aseprite 路径

通过 ASEPRITE_MCP_TOOL_PROFILE 选择工具范围：

{
  "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。

故障排查

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

致谢与许可

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

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