Docs · MCP server
Using LibreSprite with AI assistants (the MCP server)
LibreSprite’s development branch includes an MCP server: a script that lets AI assistants that speak the Model Context Protocol look at your sprite and change it. We built LibreSprite from source and called every tool to see what it really does.
On this page 6 sections
Not in LibreSprite 1.3
The MCP server was added to the master branch on 12 October 2026, after the 1.3 release. To use it today you must build LibreSprite from source. We tested commit 98f7443 (29 October 2026); details may change before the next release.
Short answer
Can LibreSprite work with AI like Claude?
Yes, with a development build. Start LibreSprite with the bundled mcp-server.js script; it serves MCP over HTTP at http://127.0.0.1:9000/mcp. Any MCP client that supports the Streamable HTTP transport can then read sprite information, layers, palettes and pixels, set pixels and palette colours, render frames as PNG, save, and run LibreSprite commands. It does not generate images by itself: it gives the assistant hands, not art.
Start the server
Open your sprite, then run the script from the Scripts menu (it ships in data/scripts/mcp-server.js). A small MCP Server window appears with Host, Port, Allowed origins, Allow CORS, Read-only and Start/Stop buttons, and the status line shows the address. LibreSprite asks for permission to open a network port the first time.
libresprite --batch sprout.ase --script data/scripts/mcp-server.js
# Warning: no UI to prompt for permissions; auto-granted net.serve for .../mcp-server.js
# Listening on http://127.0.0.1:9000/mcpOptions go through the new --set flag, for example --set host=0.0.0.0 (only do that on a trusted network, see below). Port 0 means “the first free port from 9000 to 9099”.
Connect an MCP client
Point the client at the URL the server printed. For Claude Code:
claude mcp add --transport http libresprite http://127.0.0.1:9000/mcpClients that use a JSON config file take the same URL with the HTTP transport type. The server speaks MCP protocol versions 2025-03-26 and 2025-06-18 and answers with plain JSON (no streaming).
The 11 tools, as we tested them
Our demo sprite was open (32 × 32, layers Body and Leaf, 4 frames). We sent each request with curl and recorded the reply:
| Tool | What it does | Our result |
|---|---|---|
sprite_info | File name, size, colour mode, layer and frame counts, active layer and frame | 32 × 32, rgb, 2 layers, 4 frames |
layers_list | Layers from the bottom: name, visible, editable, kind, cel count | Body and Leaf, 4 cels each |
sprite_image | A frame as a PNG image the assistant can look at | Returned a base64 PNG |
pixel_get | One pixel’s colour as #RRGGBBAA | #6abe30ff at 16,16 |
pixel_set | Set one pixel (hex or r,g,b,a). Not undoable. | Set 0,0 to red; the saved file confirms it |
palette_get / palette_set | Read the palette, or change one entry | Listed our 9 colours |
sprite_save / sprite_save_as | Save, or save a copy to a path | Wrote after-mcp1.png…4.png (one per frame) |
command_info | Describe a LibreSprite command’s parameters | SpriteSize: use-ui, width, height… |
run_command | Run any LibreSprite command by name (Close and Exit excluded) | Some commands open dialogs that need a person |
Because the tools work pixel by pixel, assistants are good at inspecting sprites, recolouring palettes, small fixes, batch saves and driving commands, and slow at drawing whole pictures.
Security notes
- No authentication. Anything that can reach the port can read and change your open sprite and save files where LibreSprite can write. Keep the default host
127.0.0.1(this computer only). - Browser protection: requests from web pages on other origins are refused. Our request with
Origin: http://evil.examplegot HTTP 403. Only localhost origins are allowed by default. - Read-only mode disables the tools that change things. Use it when you only want an assistant to look.
- Headless runs auto-grant permissions: without a window there is nobody to ask, so the script’s network permission is granted automatically (the warning above).
- Edits made through MCP are not undoable. Save a copy first, as the server’s own instructions advise.
A note on AI in LibreSprite
Not everyone in the community wants AI features. In March 2026 a user asked for the bundled AI image-generation example script to be removed (issue #601, now closed); that example still ships in 1.3. The MCP server is an optional script: nothing runs or connects anywhere unless you start it.
FAQ
Does LibreSprite have built-in AI?
No. LibreSprite has no AI features of its own. The development branch adds an optional MCP server so external assistants can control it, and 1.3 ships an example script that talks to a local image-generation server you run yourself.
Will the MCP server be in the next release?
It is on master, so it will likely be in the next release, but the project hasn’t announced dates or final details.
Can I use it with LibreSprite 1.3?
Not as shipped: the script relies on scripting features (an HTTP server, permissions, --set) that only exist on master.
Is it safe to expose on my network?
Not without care: there is no login. Keep it on 127.0.0.1, or use read-only mode and a firewall if you must bind to another address.
Keep going
Found something wrong or out of date? Tell us: hello@libresprite.dev. We fix mistakes within a day.