How to add Aseprite MCP Tools to Windsurf

Give AI assistants full control over Aseprite to create pixel art and animated sprites. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 205★ · stdio · no auth

Windsurf config for Aseprite MCP Tools

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

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Aseprite MCP Tools config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Aseprite MCP Tools's tools become available to Cascade.

Before you start

Python 3.13+
uv package manager
Aseprite (set ASEPRITE_PATH in .env if it is not on your PATH)

What Aseprite MCP Tools can do in Windsurf

create_canvas

Create a new sprite with the given dimensions.

add_layer

Add a new layer, optionally inside a named group.

add_group

Add a new (optionally nested) group layer.

add_frame

Append a new frame.

set_frame

Set the active frame.

set_frame_duration

Set one frame's duration in ms.

set_layer

Set the active layer (optionally creating it).

draw_pixels

Plot individual pixels with per-pixel colors.

Security

The `run_lua_script` tool executes arbitrary Aseprite Lua code on the host in batch mode — only pass scripts you trust. Several tools read and write `.aseprite` files and export images to the local filesystem.

Aseprite MCP Tools + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Aseprite MCP Tools config there under the "mcpServers" key and restart the client.

Is Aseprite MCP Tools safe to use with Windsurf?

Do I need Aseprite installed?

Yes. The server drives a real Aseprite binary in batch mode. Install Aseprite locally and set ASEPRITE_PATH in .env if it is not on your PATH, or run via the provided Docker image (which can install Aseprite via SteamCMD with Steam credentials).

How do I run it?

Add the mcpServers config block to your MCP client, pointing the uv command at the cloned repo directory and running `-m aseprite_mcp`. It requires Python 3.13+ and the uv package manager. A Docker image and docker-compose setup are also provided.

Is the raw Lua tool safe?

run_lua_script executes arbitrary, unrestricted Aseprite Lua on the host. Only pass scripts you trust.

View repo Full Aseprite MCP Tools page