mcp-storyset

MCP server for storyset.com — search, download, and recolor free illustrations directly from Claude Code (or any MCP client).

Cross-platform: works on Linux, macOS, and Windows. Python 3.10+.

Tools

Tool	Purpose
search(query, limit=20)	Search illustrations. Returns {title, slug, style, page_url, preview_url} per result.
get_illustration(slug, style="amico")	Resolve canonical PNG + SVG asset URLs for one illustration.
download(asset_url, output_dir?, filename?, recolor?)	Save an asset to disk. Optional SVG recolor map. Only accepts stories.freepiklabs.com URLs.
extract_palette(source, top=12)	List dominant hex colors in an SVG (URL or local file), sorted by frequency.
recolor_svg(source, mapping, output_path?)	Rewrite hex colors inside an SVG and save the modified copy.
search_and_download(query, limit=5, style?, format="svg", output_dir?, recolor?)	One-shot: search → resolve → save top N (with optional recolor).

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

Requirements

• Python 3.10 or newer (python3 --version)
• pip (python3 -m ensurepip --upgrade if missing)
• Outbound HTTPS to storyset.com and stories.freepiklabs.com

Install

Clone or copy this repo, then from the project root:

Linux / macOS (bash, zsh, fish):

git clone https://github.com/ReverserID/MCP-STORYSET.git mcp-storyset
cd mcp-storyset
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Windows (PowerShell):

git clone https://github.com/ReverserID/MCP-STORYSET.git mcp-storyset
cd mcp-storyset
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

Using pipx (Linux/macOS/Windows) — installs into an isolated env and exposes the mcp-storyset command globally:

pipx install .

Run standalone

The server speaks MCP over stdio. From an activated venv:

mcp-storyset
# or
python -m mcp_storyset

It blocks waiting for an MCP client on stdin/stdout — that is expected. Ctrl+C to stop.

Add to Claude Code

Quick (any OS)

claude mcp add storyset -- python -m mcp_storyset

If you installed inside a venv, pass the venv's interpreter so Claude Code does not need the venv activated:

Linux / macOS:

claude mcp add storyset -- /absolute/path/to/mcp-storyset/.venv/bin/python -m mcp_storyset

Windows:

claude mcp add storyset -- C:\absolute\path\to\mcp-storyset\.venv\Scripts\python.exe -m mcp_storyset

Manual config

Edit ~/.claude.json (user-level) or project .mcp.json:

Linux / macOS:

{
  "mcpServers": {
    "storyset": {
      "command": "/home/youruser/projects/mcp-storyset/.venv/bin/python",
      "args": ["-m", "mcp_storyset"],
      "env": {
        "STORYSET_DOWNLOAD_DIR": "/home/youruser/Downloads/storyset"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "storyset": {
      "command": "C:\\Users\\You\\projects\\mcp-storyset\\.venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_storyset"],
      "env": {
        "STORYSET_DOWNLOAD_DIR": "C:\\Users\\You\\Downloads\\storyset"
      }
    }
  }
}

If mcp-storyset is installed via pipx (or globally), "command": "mcp-storyset" with "args": [] also works.

Restart Claude Code, then verify with /mcp — storyset should be listed with 6 tools.

Usage examples

In Claude Code:

• "Find storyset illustrations about developers and download top 3 SVGs."
• "Get the rafiki style of the 'finance' illustration as PNG."
• "Search storyset for 'team meeting', show previews."
• "Show the color palette of this SVG and swap the primary color to #2196F3."
• "Download 'programmer / amico' SVG but recolor #ba68c8 → #10b981."

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 #ba68c8 purple). Workflow:

1. extract_palette(source=svg_url) → see colors + counts.
2. recolor_svg(source=svg_url, mapping={"#ba68c8": "#2196f3"}) → save remapped copy.
3. Or skip step 2 and pass recolor={...} directly to download / search_and_download.

Environment

Var	Default	Purpose
STORYSET_DOWNLOAD_DIR	~/Downloads/storyset (Linux/macOS), %USERPROFILE%\Downloads\storyset (Windows)	Default save directory for download. Created on first save.

The default path is resolved with pathlib.Path.home() so ~ expands correctly on every OS.

Troubleshooting

• python: command not found (Linux/macOS): use python3 instead, or install Python from your distro (sudo apt install python3 python3-venv python3-pip on Debian/Ubuntu, brew install python on macOS).
• claude command missing: install/upgrade Claude Code, or edit ~/.claude.json manually as shown above.
• /mcp shows the server as failed: run the command from the config in a terminal — any startup error (missing deps, wrong interpreter path) will print there.
• Permission denied writing to ~/Downloads/storyset on Linux: set STORYSET_DOWNLOAD_DIR to a writable directory (e.g. /tmp/storyset).
• Corporate proxy / TLS interception: set HTTPS_PROXY / SSL_CERT_FILE in the env block of the MCP config — httpx honors both.

Development

# from project root, in an activated venv
pip install -e .

# quick stdio smoke test
python - <<'PY'
import asyncio, sys
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(command=sys.executable, args=["-m", "mcp_storyset"])
    async with stdio_client(params) as (r, w):
        async with ClientSession(r, w) as s:
            await s.initialize()
            t = await s.list_tools()
            print("tools:", [x.name for x in t.tools])

asyncio.run(main())
PY

Expected output: tools: ['search', 'get_illustration', 'download', 'extract_palette', 'recolor_svg', 'search_and_download'].

Notes

• Storyset content is free under their license — credit required for free-tier use. See https://storyset.com/terms.
• This server scrapes public HTML. No API key.
• All file paths in tool arguments accept ~ and are resolved with Path.expanduser().