Aseprite MCP Tools

Aseprite MCP 工具

一个 Python MCP 服务，可让 AI 助手全面控制 Aseprite，用于创作像素画和动画精灵。

18 个类别共 123 种工具 — 画布、绘图、图层、动画、调色板、效果、切片、瓦片地图、导出、视觉反馈／分析工具，以及原始 Lua 逃生通道。工具集经过设计，确保大模型拥有创作优秀像素画所需的一切，而不只是基础工具：包含色相偏移的明暗色阶、有序抖动、轮廓、支持量化的复古调色板预设、洋葱皮渲染，以及用于动画制作的帧差异、边界和 lint 检查。

示例

温馨房间（Opus 5.5）

黄昏时分的等距视角卧室，女孩在写作业，动画采用 lo-fi 风格循环。 128×128，16 帧循环，以 4× 导出。

剑士：Fable 5 对比 Opus 5.5

Fable 5	Opus 5.5
基准测试剑士，以及从蓄势到收势的挥剑动作。 48×48，4 帧挥剑动画。	Opus 5.5 评析了 Fable 5 的精灵图，并以相同尺寸重新绘制。 48×48，8 帧挥剑动画。

Fable 5 的任务复现了 Lj Miranda 的 Draw Me a Swordsman 基准测试；其研究成果启发了本服务扩展工具集。

史莱姆（Opus 5.5）

一只绿色史莱姆。 32×32 静态图，以 8× 导出。

史莱姆向右弹跳，并带有挤压与拉伸效果。 43 帧动画，以 4× 导出。

剑士对战史莱姆（Opus 5.5）

剑士砍中史莱姆，史莱姆闪红、损失生命值，并弹出伤害数字。 80×58，15 帧，以 5× 导出。

相关项目

Aseprite Live – 在浏览器中实时观看 AI Agent 在 Aseprite 中绘制像素画

工具类别

类别	工具数	描述
画布	7	创建精灵图、管理图层/帧、设置活动状态
绘制	16	像素、文本行、线条、矩形、圆形、椭圆、多边形、路径、填充、渐变、等距方块
文本	3	使用位图精灵图表字体或 TrueType 字体绘制和测量文本
图层	7	删除、重命名、复制、重新排序、混合模式、合并、扁平化
选区与区域	4	移动、复制和擦除矩形区域或颜色
效果	12	描边、颜色替换、HSL 调整、有序抖动、原生 Aseprite 滤镜
动画	24	帧、图块、标签、缓动补间、传播
调色板	8	获取/设置调色板、复古预设、颜色渐变组、量化、颜色模式
变换	4	翻转、旋转、调整大小、裁剪
切片	5	命名区域、9 宫格中心、枢轴点
瓦片地图	5	瓦片地图图层、瓦片集编辑、瓦片放置
导出与导入	8	PNG、GIF、精灵图表、按图层/标签导出、在背景上预览、图像导入
检查	6	读取像素（单个图层、可见合成图，或文本行）和精灵图元数据
分析与视觉反馈	6	模型可见的精灵图预览、洋葱皮渲染、帧差异、边界、代码检查、颜色统计
质量	4	验证并清理动画一致性
场景	1	在精灵图文件之间复制图层
预览与指南	3	本地 HTTP 预览服务、工作流指南
脚本	1	用于处理上述功能未涵盖事项的原始 Lua 备用方案

画布

工具	描述
create_canvas	按给定尺寸创建新的精灵图
add_layer	添加新图层，可选择将其放入命名组中
add_group	添加新的组图层（可嵌套）
add_frame	追加新帧
set_frame	设置活动帧
set_frame_duration	设置单帧的持续时间（毫秒）
set_layer	设置活动图层（可选择创建该图层）

绘制

所有 _at 变体都以指定图层/帧为目标，并可按需创建 cel。坐标是精灵图全局坐标。

draw_rows(filename="mug.aseprite", layer_name="mug", frame_index=1, x=4, y=2,
          rows=[".WWWW..",
                ".WWWWKK",
                ".WWWW.K",
                "..WW.K."],
          legend={"W": "#F4F4F4", "K": "#8B5A2B"}, outline="#1A1C2C")

.（或图例中缺失的任何字符）表示不更改像素；read_rows 会以相同格式返回像素，因此可以读取后修改几个字符，再次绘制。

工具	描述
draw_pixels	使用逐像素颜色绘制单个像素
draw_pixels_at	在指定图层/帧上绘制像素
draw_line / draw_line_at	绘制带粗细的线条
draw_rectangle / draw_rectangle_at	绘制空心或实心矩形
draw_circle / draw_circle_at	绘制空心或实心圆形
draw_ellipse_at	使用独立的 x/y 半径绘制空心或实心椭圆
draw_polygon	根据点列表绘制空心或实心多边形
draw_path	使用点列表绘制带粗细的折线
fill_area / fill_area_at	使用油漆桶进行泛洪填充
apply_gradient_rect	在矩形中填充平滑线性渐变
draw_rows	将像素绘制为字符行并附带颜色图例，类似 ASCII 艺术；可选 1px 描边——这是放置手工挑选细节（面部、手、动物、把手）的紧凑方式
draw_iso_box	绘制实心 2:1 等距方块，边缘整洁，且每个面使用一种颜色，适用于家具和道具

文本

Aseprite 的 Lua API 不支持绘制文本，因此字形会在服务端栅格化并合成到精灵图中。支持两种字体后端：位图精灵图集字体（适合像素画——字形本身就是像素，size 会按整数倍缩放）和 TrueType .ttf/.otf 文件；除非特别指定，否则渲染时不会进行抗锯齿处理。

字体会从 ~/.aseprite-mcp/fonts 中查找：位图字体是包含 font.json 和图集 PNG 文件的目录；TrueType 字体则只是字体文件。也会列出已安装的系统字体。font 也接受直接路径。

工具	描述
list_text_fonts	列出 draw_text 可用的位图和 TrueType 字体
measure_text	返回宽度、高度、字距和基线范围——无需反复重绘，即可确定面板尺寸或让标签居中
draw_text	绘制文本，支持锚点、伪粗体、描边、投影和字间距

如果布局取决于文本内容，请先调用 measure_text：它返回的度量值与 draw_text 使用的相同，因此可以一次性将标签居中或确定底板尺寸。

measure_text(text="MODERATOR", font="minecraft", size=2, bold=1)
  -> width=115 height=15 advance_width=117 above_baseline=14 below_baseline=1 left_bearing=0

draw_text(filename="badge.aseprite", text="MODERATOR", x=64, y=17,
          font="minecraft", size=2, anchor="baseline", bold=1,
          color="#FFFFFF", shadow_color="#14237A")

锚点包括 topleft/top/topright、left/center/right、bottomleft/bottom/bottomright，以及用于将多个标签固定在同一基线上的 baselineleft/baseline/baselineright。描边和阴影会扩大印章，但不会移动字形。

font.json

{
  "name": "my-font",
  "letter_gap": 1,
  "space_width": 3,
  "sheets": [{
    "file": "sheet.png",
    "cell_w": 8, "cell_h": 8,
    "ascent": 7,
    "chars": [" !\"#$%&'()*+,-./", "0123456789:;<=>?"]
  }],
  "overrides": {
    "86": {"ascent": 7, "rows": ["#...#", "#...#", ".#.#.", "..#.."]}
  }
}

每个图集都有自己的 ascent，因此即使单元格尺寸不同，也能共用同一基线——紧凑的 ASCII 图集和更高的带重音字符图集就是这样组合成同一行文本的。图集带有边距时，origin 用于偏移单元格网格；ink_rule: "dark" 用于读取以不透明白色背景界定可变宽度字形框的图集；advance: "box" 则从字形框而非墨迹中获取字距。overrides 可用手绘行替换单个字形，适用于图集中某个字形偏离中心或过高、无法与文本行对齐的情况。

图层

工具	描述
delete_layer	按名称删除图层
rename_layer	重命名图层
duplicate_layer	复制图层及其所有单元格、不透明度和混合模式，也可选择复制到组中
reorder_layer	将图层移动到图层堆栈中的指定位置
set_layer_blend_mode	设置混合模式（正片叠底、滤色、叠加等，共 19 种）
merge_layer_down	将图层合并到下方图层
flatten_sprite	将所有图层合并为一个

选区与区域

工具	描述
move_region	剪切一块矩形像素区域并粘贴到其他位置
copy_region	将矩形区域复制到其他位置、图层或帧
erase_region	将矩形区域设为透明
erase_color	魔术橡皮擦：将指定颜色的所有像素设为透明（支持容差）

特效

像素画工具箱：干净的轮廓、遵循调色板的混色，以及多种阴影效果。

工具	描述
outline_cel	为所有不透明像素添加 1px 轮廓，或仅为区域内的形状添加轮廓
replace_color	将一种颜色替换为另一种颜色（支持容差），并保留 Alpha
adjust_hsl	调整图层单元的色相、饱和度和亮度——可用于切换调色板、制作夜景和阴影
apply_dither_gradient	使用 Bayer 4×4 有序抖动制作双色渐变
apply_dither_pattern	以指定密度均匀混合两种颜色并应用抖动

原生滤镜会在图层和帧上运行 Aseprite 自带的引擎命令：

工具	描述
outline_native	Aseprite 的轮廓命令，为不透明像素添加轮廓
adjust_hsl_native	Aseprite 的色相／饱和度／亮度滤镜
adjust_brightness_contrast	亮度／对比度滤镜
invert_colors	颜色反转
apply_convolution	卷积滤镜：模糊、锐化、边缘、浮雕……
list_convolution_matrices	列出 apply_convolution 的内置矩阵
extract_palette	从精灵图构建最佳调色板（原生颜色量化）

动画

工具	描述
add_frames	添加 N 个帧，可选设置持续时间
delete_frame	删除一个帧
set_frame_duration_all	设置每个帧的持续时间
duplicate_frame_range	将帧范围复制 N 次
copy_frame / propagate_frame_to_range	将一个帧的所有图层单元复制到其他帧
create_cel / clear_cel / copy_cel	管理图层／帧上的图层单元生命周期
propagate_cels	将选定图层的图层单元复制到整个帧范围
set_cel_position	将图层单元放置在 x,y 处
set_cel_opacity	设置单个图层单元的不透明度
offset_cel_positions	在多个帧中按增量移动图层单元
tween_cel_positions	在多个帧中对位置进行线性补间
tween_cel_positions_eased	使用缓动效果（ease_in/out、smoothstep）对位置进行补间
tween_cel_opacity_eased	使用缓动效果对不透明度进行补间
tween_cel_scale_eased	使用缓动效果和锚点对缩放进行补间
oscillate_cel_positions	正弦波运动（上下浮动、呼吸、悬停）
set_tag / delete_tag	设置或删除带方向的动画标签（正向／反向／往返）
set_layer_visibility / set_layer_opacity	设置图层级别的可见性和不透明度
set_onion_skin	配置洋葱皮 UI 偏好设置（批量使用请参阅 render_onion_skin）
get_sprite_info	精灵图元数据：尺寸、图层、帧、持续时间、标签

调色板

工具	描述
get_palette	以十六进制颜色读取调色板
set_palette	根据十六进制颜色列表设置调色板
list_palette_presets	列出内置复古调色板
apply_palette_preset	应用预设：gameboy、pico8、c64、cga、dawnbringer16、dawnbringer32、grayscale_4、monochrome
generate_color_ramp	根据基色构建从暗到亮的阴影色阶，并调整色相
quantize_to_palette	将每个像素映射到最近的调色板颜色
remap_colors_in_cel_range	在帧范围内重新映射特定颜色
set_color_mode	在 RGB、灰度和索引模式之间转换

变换

工具	描述
flip_layer	水平或垂直翻转图层单元
rotate_layer	将图层单元旋转 90/180/270°
resize_canvas	将精灵图缩放到新尺寸
crop_canvas	裁剪为矩形区域

切片

工具	描述
create_slice	创建命名矩形区域
set_slice_center	设置 9 宫格的可拉伸中心
set_slice_pivot	设置枢轴点
list_slices	以 JSON 列出所有切片的边界、中心和枢轴点
delete_slice	删除切片

Tilemap（瓦片地图）

工具	描述
create_tilemap_layer	添加一个拥有独立图块集和图块网格的瓦片地图图层
draw_on_tile	在图块集中的图块上绘制像素（自动追加新图块）
set_tiles	按网格位置在地图上放置图块
get_tile_at	读取某个网格单元占用的图块
get_tilemap_info	以 JSON 格式返回图块大小、图块数量和地图尺寸

导出与导入

工具	描述
export_sprite	导出为 PNG、GIF、JPG 等格式
export_frame	将单帧导出为 PNG，并按整数倍放大（查看作品请使用 view_sprite）
export_spritesheet	导出精灵图集（水平／垂直／按行／按列／紧凑排列），可选 JSON 元数据和按标签筛选
export_layers	每个图层导出为一个 PNG
export_tag	将动画标签导出为 GIF 或 PNG 序列
export_animation	将所有帧或一个标签导出为 GIF 或 PNG 序列，可缩放，也可选择使用纯色背景——不会更改精灵本身
import_image_as_layer	将 PNG 导入图层（参考图、预制部件）
copy_sprite	复制 .aseprite 文件

检查

工具	描述
get_pixel_color	读取一个像素的 RGBA 值
get_pixels_rect	以 JSON 格式读取矩形区域的像素
get_composite_pixel / get_composite_rect	读取某个像素或矩形区域内可见的内容（所有图层合成后的结果）
read_rows	将一个区域读取为字符行及图例——这是 draw_rows 可接收的紧凑格式
get_sprite_info	精灵元数据（动画部分也有列出）

分析与视觉反馈

批处理模式下可实现与人类艺术家使用 Aseprite UI 时相同的效果。

工具	描述
view_sprite	直接向模型返回帧图像——带缩放、像素网格和坐标标尺，便于精确修正像素
render_onion_skin	在相邻帧的半透明残影上渲染某一帧——无需打开 Aseprite 即可检查动作连贯性
compare_frames	比较两帧的差异，可指定单个图层或区域（脚是否移动了？）：返回变化像素数量、百分比和边界框
get_bounds	返回每帧所绘像素的边界框，可指定单个图层——测量上升和下降、地面线及画布边缘
lint_sprite	检查分离部件、孤立像素和游离像素，并提供坐标
get_color_stats	返回某一帧的颜色直方图——可发现调色板偏移和近似重复的颜色

view_sprite 是绘制循环的眼睛：它会以 MCP 图像内容的形式返回画面，因此模型无需导出文件再打开即可看到作品，并且可用于无法读取本地文件的客户端。使用 "3"、"1-4" 或 "1,3,6-8" 选择帧；使用 layer_name 单独查看一个图层；使用 region="x,y,w,h" 放大细节，同时保留精灵坐标标尺。

质量

工具	描述
ensure_layers_present	为指定帧范围内的图层创建缺失的 cel
validate_scene	以 JSON 格式报告缺失的图层／cel
audit_animation	检查动画帧中的重叠和超出范围的图层活动
animation_sanitize	规范化图层顺序、覆盖范围和重叠

场景

工具	描述
copy_layers_between_sprites	按名称将图层从一个 .aseprite 文件复制到另一个文件

预览与指南

工具	描述
start_preview_server / stop_preview_server	通过本地 HTTP 提供导出文件
animation_workflow_guide	如何做好动画：关键姿势、预备动作、挤压与拉伸、时序（character、idle、environment）

客户端连接时，服务还会通过 MCP instructions 发送简短的像素艺术规则（先处理轮廓、单一光源方向、线条干净、逐步检查），因此模型无需调用任何工具即可获取这些规则。

脚本编写

工具	描述
run_lua_script	在批处理模式下执行任意 Aseprite Lua（API 文档）。这是最后的手段，适用于没有专用工具支持的操作：一个脚本就能在单次启动 Aseprite 时批量执行多项操作。记得调用 spr:saveAs(spr.filename) 并使用 print() 输出结果。⚠️ 会在主机上运行不受限制的代码——仅传入你信任的脚本。

面向大模型的推荐工作流

1. 先规划调色板：为每种材质（皮肤、盔甲、刀刃）使用 generate_color_ramp，或使用 apply_palette_preset 打造复古风格。
2. 分层构建：背景／身体／装备／特效分别处理，以便独立制作动画和编辑。
3. 由粗到细绘制：先用 draw_rectangle_at／draw_ellipse_at／fill_area_at 绘制轮廓，再用 draw_rows 精修。
4. 检查作品：每完成一轮操作后使用 view_sprite（用 region 放大查看），修正并重复。使用 get_color_stats 保持调色板精简，并用 lint_sprite 检查零散和脱离的像素。
5. 有目的地添加阴影：用 adjust_hsl 处理阴影图层，用 apply_dither_gradient 进行渐变混合，并用 outline_cel 提高可读性。
6. 使用 Cel 工具制作动画：先用 propagate_cels，再用 tween_cel_positions_eased／oscillate_cel_positions；使用 view_sprite、compare_frames 和 get_bounds 检查，并用 export_animation 或 export_tag 导出。

Docker 用法

快速开始

构建并运行 Docker 镜像：

docker build -t aseprite-mcp:latest .
docker run -it --rm aseprite-mcp:latest

或者使用提供的构建脚本：

• Linux/macOS：chmod +x build-docker.sh && ./build-docker.sh
• Windows：.\build-docker.ps1

使用 Docker Compose

# Production
docker-compose up aseprite-mcp

# Development mode
docker-compose --profile dev up aseprite-mcp-dev

详细的 Docker 配置说明请参阅 DOCKER.md。

可选：通过 Steam 安装 Aseprite

若要让容器在启动时通过 SteamCMD 安装 Aseprite，请提供 Steam 凭据：

# Create a .env with STEAM_USERNAME/STEAM_PASSWORD (and optional STEAM_GUARD_CODE)
# Then
docker run --rm -i --env-file .env aseprite-mcp:latest

如果已安装，二进制文件将位于 /opt/steamapps/common/Aseprite/aseprite，并会自动识别 ASEPRITE_PATH。

本地安装

先决条件

• Python 3.13+
• uv 包管理器
• Aseprite（如果不在 PATH 中，请在 .env 中设置 ASEPRITE_PATH）

安装：

{
  "mcpServers": {
      "aseprite": {
          "command": "/opt/homebrew/bin/uv",
          "args": [
              "--directory",
              "/path/to/repo",
              "run",
              "-m",
              "aseprite_mcp"
          ]
      }
  }
}