A
licenseNot graded
qualityD
maintenanceMCP server for programmatically creating and editing Aseprite sprites, enabling AI agents to draw, manage layers and frames, and iterate until the desired result is achieved.
136 npm
MIT
spriteloom-mcp
by AlexPascu007
Use this local MCP server to create and modify pixel-art sprites and manage the SpriteLoom engine.
Check service state, backend, connection URL, process ID, and ownership without starting the model.
Generate sprites from text with configurable size, variants, seed, palette, background handling, and output directory.
Edit existing sprites by instruction while leaving source files unchanged and optionally preserving the source palette.
Inpaint selected masked regions and optionally save transparent overlay patches.
Re-view or rotate a sprite from a requested angle using the model rather than pixel rotation.
List recent MCP-owned generation metadata.
Stop the shared managed engine when idle.
Image tools return PNG previews, absolute output paths, seeds, and metadata using the local engine with no cloud API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@spriteloom-mcp generate a 64x64 pixel-art sprite of a knight with a red shield"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
spriteloom-mcp
Give Claude, Codex, and other MCP clients local tools to create and edit pixel-art sprites. This repository contains a small stdio MCP server and an agent skill. The model runs in the separate spriteloom-mlx engine. Aseprite is optional.
Based on SpriteLoom, created by Valentyn Karachevtsev (vkarach). The original project supplies the sprite workflow, prompts, image processing, protocol, and Aseprite extension. This independent integration adds agent tools and client setup. See NOTICE and the Apache 2.0 license.
Install
Set up the model engine for your machine first. The engine supports NVIDIA CUDA on Windows and MLX on Apple Silicon macOS; follow its Windows or macOS setup guide. Then install this MCP server in its own Python environment:
git clone https://github.com/AlexPascu007/spriteloom-mcp.git
cd spriteloom-mcp
uv venv --python 3.12
uv pip install -e .On Windows, use py -3.12 -m venv .venv and
.venv\Scripts\python.exe -m pip install -e . if you are not using uv.
Keep the two repositories in the same parent directory, or set
SPRITELOOM_ENGINE_ROOT to the absolute engine path. The MCP environment
contains no model runtime. The engine uses its own Python environment.
To connect a client running on a different computer to an already-running
engine, pass --service-url ws://host:8765 to the integration installer
instead. Use a trusted network or tunnel for that connection.
Preview the Codex, Claude Code, or Claude Desktop configuration changes, then apply them:
.venv\Scripts\python.exe scripts\install-agent-integration.py --all --engine-root ..\spriteloom-mlx
.venv\Scripts\python.exe scripts\install-agent-integration.py --all --engine-root ..\spriteloom-mlx --apply.venv/bin/python scripts/install-agent-integration.py --all --engine-root ../spriteloom-mlx
.venv/bin/python scripts/install-agent-integration.py --all --engine-root ../spriteloom-mlx --applyThe installer supports Codex, Claude Code, and Claude Desktop on Windows and
macOS. It preserves other configuration entries and makes backups before changes.
Use --replace to update an existing SpriteLoom entry. Restart the clients
after installation. The skill is installed for Codex and Claude Code.
Claude Desktop receives the MCP tools; see MCP.md for skill use
and manual configuration.
For another MCP client, use the absolute path to .venv/Scripts/python.exe
on Windows or .venv/bin/python on macOS as the command, with the absolute
path to mcp_entry.py as its only argument. Set SPRITELOOM_ENGINE_ROOT in
the server environment.
Related MCP server: pixelsmith
Tools
Tool | Purpose |
| Check service state without loading the model |
| Create a sprite from text |
| Edit an existing sprite by instruction |
| Redraw a mask and save a complete sprite |
| Generate a requested view of a subject |
| List saved runs and their metadata |
| Release the managed engine when it is idle |
Image tools return PNG previews, absolute output paths, seeds, and metadata.
Each run has its own folder under ~/spriteloom-output. Source files remain
unchanged. Default output is 64 by 64 pixels with one variant. Output sides
can be 1–512 pixels; variants can be 1–8. Larger work takes more time.
Editing preserves the source palette by default. Set preserve_palette=false
for new colors. Inpaint masks use white for the area to redraw and black for
the area to preserve. The complete output keeps every pixel outside the mask.
View changes depend on model quality; they do not produce an animation.
Service behavior
The first image request starts the headless engine. Multiple MCP clients
share one engine and one model allocation. Requests run in sequence.
The engine stops after ten idle minutes by default. Status checks do not
reset this timer. stop_service can stop only a managed, idle engine.
It does not stop an independently launched engine.
The default connection is local, at 127.0.0.1:8765. Standard output carries
only MCP messages. Engine logs go to ~/.cache/spriteloom-mcp.
No cloud image API or API key is needed.
Environment settings:
SPRITELOOM_ENGINE_ROOT: engine checkout with its.venvand model cache.SPRITELOOM_OUTPUT_DIR: output directory; legacySPRITELOOM_OUTalso works.SPRITELOOM_PORT: local engine port.SPRITELOOM_IDLE_SECONDS: idle shutdown delay;0disables it.SPRITELOOM_URL: explicit WebSocket connection to an existing engine. This mode does not start or stop the engine. Use a trusted connection.
Development
uv pip install -e '.[dev]'
.venv/bin/python -m pytest -qThis server uses the official Python MCP SDK, pinned to 1.30.0.
Its design follows patterns from the official
filesystem server
and GitHub MCP server: a separate
stdio process, clear tool schemas, tool annotations, and explicit client setup.
See VALIDATION.md for local test results and model limits.
Version 0.2 replaces the earlier spriteloom_generate, spriteloom_edit, and
spriteloom_inpaint names with the names above. Inpaint now returns a complete
edited sprite; set overlay_path to save a separate transparent patch. Update saved prompts after upgrading.
Model weights and Aseprite binaries are not distributed in this repository.
Available Tools
7 toolsedit_spriteEdit spriteB
Edit an existing sprite with an instruction. The source dimensions are used when width or height is omitted. preserve_palette keeps the source palette unless set to false. The source file is never changed.
Inputs: prompt (required), image_path (required), seed, width, +6 more.
generate_spriteGenerate spriteB
Generate one or more pixel-art sprites from a prompt. Width and height are 1..512 pixels. Each result is saved in a unique output directory and returned as a PNG preview.
Inputs: prompt (required), seed, width, height, +4 more.
inpaint_spriteInpaint spriteB
Inpaint a selected region of an existing sprite. image_path and mask_path must have equal dimensions. The returned patch is clipped to the original binary mask, then composited with source pixels outside the mask preserved. Set overlay_path to save transparent patch PNGs as well as composite PNGs.
Inputs: prompt (required), mask_path (required), image_path (required), seed, +6 more.
list_generationsList SpriteLoom generationsBRead-onlyIdempotent
List recent MCP-owned generation metadata. Only metadata files with the SpriteLoom MCP ownership marker are read; arbitrary directories and files are ignored.
Inputs: limit, output_dir.
rotate_spriteRotate sprite viewB
Re-view a sprite from a requested direction with SpriteLoom's instruction mode. Provide the subject and view explicitly. This uses the model; it does not rotate pixels. image_path is never changed.
Inputs: view (required), subject (required), image_path (required), seed, +5 more.
spriteloom_statusSpriteLoom statusARead-onlyIdempotent
Read the local SpriteLoom service state. This never starts the model and returns state, backend, WebSocket URL, process ID, and ownership.
Inputs: no named parameters.
stop_serviceStop SpriteLoom serviceAIdempotent
Explicitly stop the shared headless SpriteLoom service. Generation tools share the service; it also stops after ten idle minutes by default.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
A3.6/5.0
Scored across 7 tools
Disambiguation4/5
Six of seven tools are cleanly separated by action: generate, edit, inpaint, rotate, list, stop, status. The main risk is edit_sprite vs rotate_sprite, since both take an existing image plus an instruction; the rotate description explicitly says it re-views rather than rotates pixels, which mitigates but does not eliminate the overlap.
Naming Consistency4/5
Most tools follow a consistent verb_noun pattern (generate_sprite, edit_sprite, inpaint_sprite, rotate_sprite, list_generations, stop_service). spriteloom_status breaks the pattern by being noun-first with a vendor prefix, a minor deviation within an otherwise predictable set.
Tool Count5/5
Seven tools is well-scoped for a sprite generation service: four generation/editing operations plus lifecycle and listing helpers. No tool appears redundant or superfluous.
Completeness4/5
Core lifecycle is covered: generate, modify (edit/inpaint/rotate), list, status, stop. Minor gaps exist — no delete/cleanup of generated outputs, no get-by-id detail fetch for a single generation, and no explicit service start — but these are workable around the filesystem.
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues
Related MCP Connectors
MCP server for Pixapi: check live credit pricing and balance, then generate images and video.
Generate authentic pixel art - sprites, animations, and tilesets - from any MCP client
Generate AI images and videos from any compatible MCP client.
Generate, edit, style-match, turn, and animate game-ready pixel art at exact sizes.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn MCP server that lets AI agents create, edit, and animate pixel-art sprites, with PNG previews after every step and support for export to GIF/APNG/spritesheets.48,326 npmMIT
- FlicenseNot gradedqualityCmaintenanceEnables MCP clients to create and edit pixel art and animations through a local-first editor, sharing the same project, editing commands, and undo history with the GUI.-
- AlicenseNot gradedqualityCmaintenanceEnables agents to generate local SDXL pixel art assets from text prompts, run batch manifests, list generated assets, create spritesheets, and export Phaser atlas JSON through MCP tools.MIT