Install with the command above, using setup --no-register, then add:

{
  "mcpServers": {
    "aseprite": {
      "command": "python",
      "args": ["-m", "aseprite_claude_connector"],
      "env": {
        "ASEPRITE_MCP_BACKEND": "headless",           // or "live" — see below
        "ASEPRITE_PATH": "C:/Program Files/Aseprite/Aseprite.exe"
      }
    }
  }
}

ASEPRITE_PATH is auto-detected on common installs (Steam and standalone) if you omit it.

git clone https://github.com/UmarMuhammad18/aseprite-claude-connector
cd aseprite-claude-connector
pip install -e .

• status — Report backend health plus this server's version and whether a newer release exists.
• get_sprite_info — Get the active sprite's size, color mode, and layer/frame/tag lists.
• describe_sprite — Summarize the active sprite in one call: size, color mode, the layer tree with visibility and blend modes, frame timing, tags, slices, palette, the selection, and what's active.
• get_pixel — Read one composited pixel (all layers) at (x, y) as #rrggbbaa.
• set_sprite_metadata — Attach typed key/value metadata to the sprite (Aseprite's Properties system — stored in the .aseprite file itself).
• get_sprite_metadata — Read the sprite's typed key/value metadata (Properties).
• get_pixels — Read a composited pixel region as a grid of #rrggbbaa strings — the AI feedback loop for 'what does the canvas look like now'.

• look — See the canvas: returns a frame as an image, scaled up with sharp pixels.
• look_animation — See an animation: returns a tag or frame range as one image, frames left to right and top to bottom.
• look_onion — See motion: returns frame as an image with earlier frames ghosted in red and later frames in blue, so the whole arc shows at once.

• open_sprite — Open a sprite file and make it the active document; returns its filename, size, and frame/layer counts.
• save_sprite — Save the active sprite to disk: to path if given (save-as; the document's filename follows it), else to its own filename — errors if the sprite is untitled and no path is given.
• close_sprite — Close the active sprite.
• set_active_sprite — Live editor only: make one of the open documents active, found by exact filename or basename match (e.g. "turret.aseprite").
• list_sprites — Live editor only: list every open document — filename (or "(unsaved)"), size, frame/layer counts, unsaved-changes flag, and which one is active.

• create_sprite — Create a new sprite.
• expand_canvas — Grow (or shrink, with negatives) the canvas per side WITHOUT scaling content — existing pixels keep their positions relative to the old origin.
• import_spritesheet — Slice a sheet PNG into animation frames: cells are read row-major at the given frame size onto a new "imported" layer, adding frames as needed.

• add_layer — Add a new empty layer (optionally named) at the top of the stack.
• add_group — Add a layer group.
• move_layer_to_group — Move a layer inside a layer group.
• list_layers — The full layer tree, top of stack first: name, path, kind (image/group/tilemap), visibility, and opacity — including layers nested in groups (which get_sprite_info lists only at the top level).
• delete_layer — Delete the layer with the given name.
• rename_layer — Rename a layer.
• set_layer_visibility — Show or hide a layer.
• set_layer_opacity — Set a layer's opacity (0-255).
• flatten_sprite — Flatten all layers into a single layer.
• set_layer_blend_mode — Set a layer's blend mode.
• duplicate_layer — Duplicate a layer (with its cels) above the original.
• merge_layer_down — Merge a layer into the layer directly beneath it.
• move_layer — Reorder a layer in the stack.
• import_image_as_layer — Import an external image file (PNG, etc.) into a new layer at (x, y) — a reference/trace layer for concept-art intake.

• add_frame — Append a new empty frame.
• duplicate_frame — Duplicate frame number (1-based).
• delete_frame — Delete frame number (1-based).
• set_frame_duration — Set frame number's duration in milliseconds.
• add_frames — Append count empty frames in one undo step.
• set_frame_durations — Set every frame in [from_frame..to_frame] to ms milliseconds.
• reverse_frames — Reverse frame order (cels on every layer, plus durations) — the whole sprite by default, or the inclusive [from_frame..to_frame] range.
• set_onion_skin — Configure the editor's onion-skin view: on/off, ghost counts each direction, and whether ghosting stays inside the current tag.

• clear_cel — Empty the cel at the given layer + frame (transparent).
• set_cel_position — Move the cel's top-left origin to (x, y).
• set_cel_opacity — Set the cel's opacity (0-255).

• draw_pixels — Set individual pixels: pixels is a list of {"x": int, "y": int, "color": "#rrggbb[aa]"}.
• draw_polyline — Stroke connected line segments through points (ordered [x, y] pairs); close=True joins the last point back to the first.
• draw_rectangle — Draw a rectangle on the active layer + frame.
• draw_line — Draw a 1px line from (x1,y1) to (x2,y2).
• draw_circle — Draw a circle centered at (center_x, center_y).
• fill_area — Flood-fill the contiguous same-color region at (x, y).
• draw_ellipse — Draw an ellipse centered at (center_x, center_y) with independent x/y radii.
• draw_gradient — Fill a rectangle with a linear gradient from color1 to color2.
• apply_dither — Fill a rectangle with a uniform ordered (Bayer 4x4) dither mixing color1 and color2.
• add_outline — Add a 1px outline around the opaque pixels of a layer, in color — readability against busy backgrounds.

• get_palette — Return the active sprite's palette as #rrggbbaa hex strings.
• set_palette_color — Set palette entry index to color (#rrggbb or #rrggbbaa).
• add_palette_color — Append color to the palette and return its new index.
• set_palette — Replace the whole palette with colors (list of #rrggbb/#rrggbbaa).
• apply_preset_palette — Replace the palette with a built-in preset: gameboy | pico8 | cga.
• generate_color_ramp — Generate a dark->light shading ramp from base_color and APPEND it to the palette in order — ready for palette_ramp_walk.
• extract_palette_from_image — Extract a palette (median-cut) from an external image file and, by default, set it as the active sprite's palette — the concept-art → locked-palette step.
• sort_palette — Reorder palette swatches by luminance (default), hue, or saturation.
• palette_from_sprite — Derive the palette FROM the sprite's actual pixels (Aseprite's color quantization) — the inverse of quantize_to_palette.
• load_palette — Replace the sprite's palette from a palette file (.gpl, .pal, .ase, .png strip — anything Aseprite reads).
• save_palette — Write the sprite's palette to a file (.gpl, .pal, .png — by extension).
• apply_bundled_palette — Apply one of Aseprite's bundled extension palettes by resource ID — e.g. DB16, DB32, ARQ4, EDG16 (availability depends on the installed palette extensions).

• replace_color — Replace every pixel matching from_color (within tolerance, a 0-255 RGB distance) with to_color across the active cel, preserving each pixel's alpha unless to_color carries its own.
• quantize_to_palette — Snap every opaque pixel of the active cel to its nearest color in the sprite's palette (alpha preserved) — enforce palette discipline after intake or shading.
• adjust_hsl — Shift the active cel's colors in HSL: hue_shift degrees (-360..360), saturation a multiplier (1.0 = unchanged), lightness a delta (-1..1).
• get_color_stats — Return a color histogram of the composited sprite: distinct opaque color count, total opaque pixels, and the top most-used colors with counts — a palette-drift check for the art-QA loop.

• apply_shading — Palette-constrained shading: brighten toward the light and darken away from it, snapping every pixel to the nearest palette color.
• palette_ramp_walk — Shade by WALKING the arranged palette ±N indices toward lighter/darker (per light direction), instead of snapping to the luminance-nearest color — so hand-ordered shading ramps are respected.

• adjust_brightness_contrast — Adjust the active cel's brightness and contrast, each -100..100 (0 = unchanged).
• invert_colors — Invert the active cel's RGB (alpha untouched).
• desaturate — Convert the active cel to grayscale (Rec. 601 luma), keeping alpha.
• box_blur — Blur the active cel with an alpha-weighted box kernel.
• sharpen — Sharpen the active cel (unsharp mask over a 3x3 neighborhood).

• paint_with_stamp — Stamp an image at each [x, y] in points (points are stamp centers).

• draw_iso_box — Draw a 2:1 isometric box.
• draw_iso_cylinder — Draw a vertical isometric cylinder (tank/silo/chimney): top ellipse + shaded body + front rim, auto-shaded from color.
• fill_polygon — Scanline-fill an arbitrary polygon given points (a list of [x, y] pairs, in order).
• iso_recessed_panel — Draw a recessed docking socket/port on an isometric face — a light lit lip framing a dark recessed interior.

• select_rectangle — Set a rectangular selection.
• select_all — Select the whole canvas.
• deselect — Clear the current selection.
• select_ellipse — Select an ellipse inscribed in the given rectangle.
• select_by_color — Select every pixel matching color (composited, within tolerance 0-255 per channel) — a global magic wand.
• invert_selection — Invert the current selection against the canvas bounds.
• get_selection — Report whether a selection exists and its bounding rectangle.
• erase_area — Erase pixels to transparent.

• flip_sprite — Flip the whole sprite horizontally or vertically.
• resize_sprite — Scale the whole sprite to new pixel dimensions.
• crop_sprite — Crop the sprite to the given rectangle.
• rotate_sprite — Rotate the whole sprite by 90, 180, or 270 degrees clockwise (lossless).
• autocrop_sprite — Trim transparent borders: shrink the canvas to the union of visible content across all layers and frames (Sprite > Trim).
• set_color_mode — Convert the sprite between rgb | gray | indexed color modes.

• create_slice — Create a named slice (atlas region) at the given rectangle.
• set_slice_pivot — Set a slice's pivot point, in pixels relative to the slice's top-left.
• set_slice_center — Set a slice's 9-patch stretchable center rectangle (relative to the slice).
• list_slices — List every slice with its bounds, pivot, and 9-patch center.
• delete_slice — Delete the slice with the given name.

• create_tag — Create an animation tag named name spanning frames from_frame..to_frame (1-based).
• delete_tag — Delete the animation tag named name.
• list_tags — List animation tags with their frame ranges.
• rename_tag — Rename the animation tag old_name to new_name.
• set_tag_color — Set the timeline label color of the tag name (#rrggbb or #rrggbbaa).
• set_tag_range — Move the tag name to span frames from_frame..to_frame (1-based, inclusive; validated against the sprite's frame count).
• set_tag_direction — Set the playback direction of the tag name: forward | reverse | pingpong | pingpong_reverse.

• create_tilemap_layer — Create a tilemap layer with its own tileset on a tile_width x tile_height grid.
• add_tile — Append an empty tile to a tilemap layer's tileset; returns the new tile's index and the tileset size.
• draw_on_tile — Set pixels on one tile of a tilemap layer's tileset.
• set_tiles — Place tile references on a tilemap layer's cel.
• get_tilemap_info — Read a tilemap layer: tile size, tileset length, and the cel's grid size, pixel position, and tile-index grid (tiles as rows of columns, flip flags stripped; capped at 64x64 with truncated set).
• export_tileset — Export a tilemap layer's tileset as a horizontal PNG strip (plus an Aseprite JSON atlas if data_path is given).

• tween_frames — Insert count in-between frames between from_frame and to_frame that slide the start frame's art toward where the end frame's art sits, so it works for moved cels and for art redrawn in a new place.
• tween_cel_opacity — Fade a layer's cels across [from_frame..to_frame]: opacity interpolates from from_opacity to to_opacity (0-255) with the chosen easing.
• smear_frame — Append a motion-smear frame blending from_frame and to_frame: overlapping pixels averaged, single-frame areas ghosted at half alpha — a pixel-content smear.
• frame_diff — Pixel-exact diff of two composited frames: changed-pixel count and ratio, the bounding box of the change, and whether they're identical.
• render_onion_composite — Write a PNG of frame with up to prev earlier frames ghosted in red and next later frames ghosted in blue (Aseprite's onion-skin convention) at the given ghost opacity — so you can see the motion arc in one image.

• export_sprite — Export the active sprite to a file; format is chosen by out_path extension (.png, .gif, ...).
• export_spritesheet — Pack all frames into a single sprite-sheet image (optionally writing a JSON atlas to data_path).
• export_layers — Export every image layer (recursing into groups) as its own PNG in out_dir, named <sanitized-layer-name>.png.
• export_tags — Export each animation tag's frame range as its own file in out_dir: an animated <tag-name>.gif (format="gif", default) or a horizontal <tag-name>.png strip (format="png").

• export_unity_sprite — Export a horizontal sprite sheet AND write the Unity .meta beside it, pre-sliced into named Multiple-mode sprites (one per frame) — one action, no manual Sprite Editor pass.
• export_unity_slices — Export the sprite as a single PNG AND write a Unity .meta with one Multiple-mode sprite per named slice, each carrying that slice's pivot — so an atlas laid out with slices imports into Unity already sliced and pivoted.

• measure_padding — Measure the transparent 'sticker' padding around the content: content bounding box, per-side padding (left/right/top/bottom), fill ratio, and distinct opaque color count.
• qa_sweep — Audit the active sprite against project conventions and return per-check pass/fail.

• batch_export — Export every .aseprite in folder (first frame) to an image, optionally integer-upscaled by scale.
• batch_resize — Resize every .aseprite in folder (first frame, nearest-neighbor) and write images to out_dir.
• batch_apply_palette — Palette-lock every .aseprite in folder: snap each sprite (first frame, alpha preserved) to a palette and export images to out_dir.

• select_frame — Make a frame active, so the next edits land on it.
• select_layer — Make a layer active, so the next edits land on it.
• undo — Undo the last edit on the active sprite (live editor).
• redo — Redo the last undone edit (live editor).

• get_editor_state — Live editor only: current zoom, scroll, and which sprite pixel the mouse is over — lets an agent know what the artist is looking at.
• set_editor_view — Live editor only: set the viewport zoom (1.0 = 100%) and/or scroll — e.g. zoom to the region you're about to edit so the artist can watch.
• set_symmetry — Live editor only: set mirror-painting symmetry — mode is none, horizontal (mirror across a vertical axis), vertical, or both; optionally place the axis lines.
• ask_point — Live editor only: ask the ARTIST to click a point on the canvas (pivot, anchor, paint origin).
• get_asked_point — Poll the result of ask_point: done false while waiting, then the clicked x/y (or cancelled if the artist pressed Esc).
• cancel_ask_point — Withdraw a pending ask_point request (e.g. the artist stepped away and you're moving on).
• show_choice_dialog — Live editor only: pop a small dialog IN Aseprite with a message and up to 4 option buttons (e.g. approve/redo).
• get_dialog_choice — Poll the result of show_choice_dialog: done false while the dialog is open, then the chosen button text.
• watch_changes — Live editor only: start counting edits the ARTIST makes to the active sprite (via Sprite.events).
• get_watched_changes — Poll the change counter started by watch_changes (reset=True zeroes it after reading).
• stop_watching_changes — Detach the watch_changes listener.

• run_lua — Run arbitrary Lua inside Aseprite and return its result (advanced escape hatch — equivalent to local code execution).