Skip to main content
Glama
raihanmd

Aseprite MCP

by raihanmd
OverviewSchemaRelated ServersDiscussionsAdmin
TypeScript
Local

Aseprite MCP

Create and revise editable pixel art in a running Aseprite editor from an AI client. This project provides a local MCP server, an Aseprite Lua extension, and a pixel-art skill that guides the agent through briefs, visual checks, and revisions. Saved-file batch tools are available separately.

Codex or OpenCode  <-- stdio -->  MCP server  <-- paired localhost WebSocket -->  Aseprite extension

The project is pre-release. Its verification recipes distinguish unit tests, CLI checks, live editor behavior, and human review. A successful tool call alone does not prove that an animation looks good.

Quickstart

You need Bun, a local Aseprite installation with scripting support, and Codex or OpenCode. The extension package step also needs zip. From this repository's root:

bun install
bun run setup
bun run package:extension
bun run install:harness

Review the install preview, then run bun run install:harness --apply to add only this MCP entry and the shared art skill to your global Codex and OpenCode setup. The installer refuses conflicting entries or customized skill copies; it does not replace unrelated client settings. See installation and recovery before applying it on an existing setup.

In Aseprite, open Edit > Preferences > Extensions > Add Extension and select the newly built dist/aseprite-mcp-*.aseprite-extension. Start a fresh AI-client session, then choose File > Connect Aseprite MCP... in Aseprite. Run bun run pairing-token in your own terminal to obtain the local port and token for that dialog. Never paste the token into chat, an issue, or a screenshot. The command does not install or start another MCP server.

Ask the client to call get_editor_status before drawing. A first art request could be:

Use the aseprite-pixel-art skill and Aseprite MCP to make a 32 × 32 blue potion icon on a transparent background. Show me the preview before saving anything.

The AI should show the result for review, then revise the same editable document when you request a change. The usage guide explains live editing, saved-file mode, and what to expect from the skill.

Screenshots and a short installation/demo video are TBA until a repeatable desktop run is recorded. There are no placeholder images presented as a finished result.

Related MCP server: aseprite-mcp

What is included

  • Live tools: create sprites and layers, draw and revise pixels or shapes, inspect previews, work with animation, palettes and selections, and save or export on request.

  • Saved-file tools: run separate Aseprite CLI jobs on named files. They cannot see unsaved editor changes and do not silently replace a live workflow.

  • Pixel-art skill: the maintained, bundled art instructions installed for both supported clients. A skill-only updater handles later revisions.

  • Verification skill: project-local tests for live editing, animation, art controls, export, and batch work.

The server connects only on localhost and requires a private pairing token. Local tools can change artwork; review the requested target document and output path before approving an agent action. The repository does not bundle or redistribute Aseprite. Architecture and troubleshooting cover the connection in more detail.

Project docs

Contributions are described in CONTRIBUTING.md. This repository's code is MIT licensed; the offline Aseprite API documentation snapshot retains its separate upstream notice.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Resources

Related MCP Connectors

Related MCP Servers

  • aseprite-mcp

    VukasinTheProgrammer
    A
    license
    Not graded
    quality
    B
    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

  • aseprite-ai-artist

    with-pebbly
    A
    license
    A
    quality
    A
    maintenance
    Enables AI agents to create and edit pixel art in a live Aseprite window, with tools for drawing, selection, transformation, and animation.
    4
    18
    1,901 npm
    290
    MIT

  • Aseprite MCP Tools

    midarikawa
    A
    license
    B
    quality
    C
    maintenance
    Enables AI assistants to create and edit pixel art and animated sprites in Aseprite through 104 tools covering drawing, layers, animation, palettes, tilemaps, exports, visual analysis, and raw Lua scripting.
    116
    MIT