Skip to main content
Glama

Aseprite MCP

让 AI 成为你的像素画创作搭档

通过 Model Context Protocol,在 Aseprite 中绘制、修改和预览像素画。

中文 · English

PyPI Python License: MIT


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 安装路径],且已经安装了扩展并启用。

Related MCP server: Aseprite MCP

安装 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.1。

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

    查看脚本状态:

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

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

注意事项:

  • 1.Agent工作时,尽量不要在画布上绘制,以免干扰实时协作。

  • 2.确保扩展与服务版本匹配,否则可能导致连接失败或功能异常。

扩展默认自动连接 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",
      // 0.5.1默认共享;--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。选择一种服务配置即可,同一端口只运行一份服务。

功能

功能

说明

实时协作

读取和编辑已经打开的文档,包括未保存画布

像素与图层

新建 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

core,cli同时启用

core(默认)

目前9 个实时工具核心入口

cli

116 个磁盘文件工具,不建立实时连接

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

自定义端口

通过启动参数修改服务端口,例如:

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

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

参数

值

用途

--shared

共享模式的兼容参数;0.5.1的实时连接默认共享,可省略

使用范围

  • 实时绘制以普通可编辑 RGB 图层为范围;非 RGB、锁定层、背景层、参考层和 Tilemap 等不支持的编辑会明确拒绝。调色板、特效、补间和 Tilemap 尚未迁移为实时能力。

  • 编辑不会自动保存;保存为 .aseprite 或 .ase 时需明确指定路径,覆盖已有文件需显式设置覆盖参数。

  • 撤销与重做针对文档最新历史,也可能涉及手动编辑。较大操作可能触发像素、复制或执行时间预算,需要缩小批次。

  • 实时后端操作内存文档,CLI 后端操作磁盘文件。断线不会自动切换到 CLI;避免同时通过两种方式写入同一个磁盘文件。

  • 服务仅监听本机回环地址。重连后需重新读取文档列表,不能复用旧会话和文档 ID。

故障排查

问题

处理方式

找不到 uv 或 uvx

安装后重开终端与客户端,或在客户端配置中使用可执行文件的绝对路径

扩展未连接

确认服务已由 MCP 客户端启动、扩展已启用、WebSocket 权限已允许,双方端口一致

端口被占用

当前源码默认共享连接;普通旧服务或其他程序占用时先停止或改端口

Transport closed

旧 MCP 通道已结束;使用共享模式后重新建立客户端连接,必要时重启客户端

版本不匹配

安装同版本的服务和扩展;可使用 aseprite-mcp==0.5.1 固定版本

找不到文档或修订冲突

重新读取文档列表与信息,使用当前会话和修订

预览图片未显示

确认客户端支持 MCP 图片内容,并缩小预览区域或缩放倍数

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

致谢与许可

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

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

Available Tools

10 tools
apply_operationsA

在指定修订执行原子批次,一次撤销。layer={kind:id或ref,value:标识},frame默认1。 支持 create_layer(ref,name)、set_opacity(layer,opacity)、pixel(layer,x,y,rgba)、 rectangle/ellipse(layer,x,y,width,height,rgba,filled=true)、pixels(layer,points=[{x,y,rgba}])、 line(layer,x1,y1,x2,y2,rgba,thickness=1)、clear_region(layer,x,y,width,height)、 write_region(layer,x,y,width,height,encoding=rgba|rle,mode=replace|source_over, pixels=[[r,g,b,a],...]或runs=[{count,rgba},...])。区域像素按行优先,RGBA为0–255整数。

Inputs: operations (required), session_id (required), document_id (required), expected_revision (required), +2 more.

create_spriteC

创建未保存的 RGB 文档。

Inputs: width (required), height (required), session_id (required), request_id.

get_connection_statusA

读取实时会话、软件版本、本机端点及已启用能力集。

Inputs: no named parameters.

get_document_infoC

读取显式内存文档,标识仅在当前会话有效。

Inputs: session_id (required), document_id (required).

get_previewC

直接返回指定修订/帧的 PNG 图片及元数据;整数最近邻缩放。

Inputs: session_id (required), document_id (required), expected_revision (required), frame, +2 more.

list_documentsC

列出显式编辑器会话中的内存文档。

Inputs: session_id (required).

read_pixelsA

读取普通 RGB 图层原始像素(不合成透明度)。region={x,y,width,height}; 按行优先返回 pixels=[[r,g,b,a],...] 或 encoding=rle 的 runs=[{count,rgba},...]。 空 Cel 返回透明像素,帧从1开始,必须匹配 expected_revision。

Inputs: layer (required), region (required), session_id (required), document_id (required), +3 more.

redoC

重做显式文档,要求匹配修订。

Inputs: session_id (required), document_id (required), expected_revision (required), request_id.

save_spriteC

显式保存文档;未命名文档必须指定路径。

Inputs: session_id (required), document_id (required), expected_revision (required), path, +2 more.

undoD

撤销显式文档,要求匹配修订。

Inputs: session_id (required), document_id (required), expected_revision (required), request_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 10 tools

    Disambiguation4/5

    Each tool has a largely distinct purpose: apply_operations mutates, read_pixels returns raw RGBA, get_preview returns a PNG, and get_document_info returns metadata. The read-oriented trio (read_pixels/get_preview/get_document_info) could occasionally be confused since all surface document state, but the descriptions clarify the differing output formats.

    Naming Consistency4/5

    Most tools follow a clear verb_noun pattern (read_pixels, create_sprite, get_preview, list_documents, save_sprite, get_connection_status). The only deviations are the conventional bare undo/redo, which is a minor, readable exception rather than a convention break.

    Tool Count5/5

    Ten tools is well-scoped for a sprite editor integration, and the heavy drawing surface is wisely consolidated into a single apply_operations batch tool rather than exploding into dozens of individual drawing tools. Each tool earns its place.

    Completeness3/5

    Core flows (create, draw/batch-edit, read, save, undo/redo) are covered, but notable gaps remain for an animation-oriented tool: no frame creation/management despite frame-indexed tools, no delete_layer or close/delete document, and no export beyond save. These missing operations will create dead ends for animation or cleanup workflows.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Enables AI assistants to automate Aseprite tasks such as sprite sheet export, frame extraction, and Lua scripting for sprite manipulation.
      21
      35 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to drive Aseprite for pixel-art creation, including sprite setup, grid-based drawing, layer/frame/tag management, reference image import, and export, with rendered previews after every mutation.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives AI assistants headless control of the pixel-art editor by wrapping its command line and complete Lua scripting API. It enables inspecting sprite metadata, creating new sprites, exporting frames and packed spritesheets, and editing pixels, layers, frames, tags and palettes.
      MIT