mcp-storyset — Storyset Illustrations MCP Server

MCP server for storyset.com — search, download, and recolor free illustrations from any MCP client.

Runs as a remote MCP server on Cloudflare Workers (McpAgent + Durable Objects, agents SDK).

Try it

It's already deployed and free to use — no install, no signup, no API key:

https://storyset-mcp.engdawood.com/mcp

Claude Code:

claude mcp add --transport http storyset https://storyset-mcp.engdawood.com/mcp

Claude Desktop / Cursor / Windsurf — add to your MCP config:

{
  "mcpServers": {
    "storyset": {
      "type": "http",
      "url": "https://storyset-mcp.engdawood.com/mcp"
    }
  }
}

Just poke at it — no client setup:

npx @modelcontextprotocol/inspector https://storyset-mcp.engdawood.com/mcp

Then ask it: "Find storyset illustrations about developers and give me the top 3 SVGs."

Transports: /mcp (Streamable HTTP, modern clients) and /sse (legacy clients).

Tools

• search(query, limit=20) — Search illustrations. Returns the query, a count, and results carrying title, slug, style, page URL and preview URL. Limit 1–60.
• get_illustration(slug, style="amico") — Resolve one illustration's canonical PNG + SVG asset URLs.
• download(asset_url, recolor?, inline=false) — Resolve an asset and return filename, content type, byte size, encoding and a ready-to-use URL. An optional recolor map rewrites SVG hex colors.
• extract_palette(source, top=12) — List the dominant hex colors in an SVG, sorted by frequency. Top 1–64.
• recolor_svg(source, mapping, inline=false) — Rewrite hex colors in an SVG and get back a URL serving the modified copy, plus per-color replacement counts.
• search_and_download(query, limit=5, style?, format="svg", recolor?, inline=false) — One-shot: search, resolve, then fetch the top N. Limit 1–20.

Styles: amico, bro, cuate, pana, rafiki.

How assets come back

Tools return a URL, not the file bytes. Illustrations routinely run past 100 KB, and dumping that into a model's context is wasteful — so download, recolor_svg, and search_and_download hand back a fetchable URL plus metadata.

Pass inline: true only when you actually need to read or transform the markup. SVGs come back as UTF-8 text, PNGs as base64. Anything over 64,000 bytes is dropped regardless, with the URL still available. Recoloring raw markup is the one exception — there is no source URL to regenerate from, so it always returns inline.

For a recolored SVG, the returned URL points back at the Worker, which re-fetches the original and re-applies the mapping on each request. Same inputs always produce the same bytes, so responses are cached for 24 hours.

Recolor cheatsheet

Storyset SVGs store colors as inline style="fill:#xxxxxx". The primary brand color is usually the most-frequent hex in the palette (often the #ba68c8 purple). The workflow:

1. Call extract_palette on the SVG URL to see colors and counts.
2. Call recolor_svg with a mapping such as {"#ba68c8": "#2196f3"} to get a URL serving the remapped SVG.
3. Or skip step 2 and pass recolor directly to download or search_and_download.

Mappings take 3- or 6-digit hex, case-insensitive. Recolor is SVG-only — it is rejected on PNG and silently skipped when requesting PNG format.

Tech stack

Cloudflare Workers, TypeScript, Durable Objects, the agents SDK, and the official MCP TypeScript SDK. Asset downloads are restricted to stories.freepiklabs.com; any other host is rejected.

Notes

Storyset content is free under their license — credit is required for free-tier use. See storyset.com/terms . This server scrapes public HTML: no API key, no authentication.