iconscout-mcp

MCP server for the Iconscout API: search and download icons, illustrations, 3D assets and Lottie animations directly from an AI agent.

Setup

Get API credentials at iconscout.com/api, then set environment variables:

ICONSCOUT_CLIENT_ID=your-client-id
ICONSCOUT_CLIENT_SECRET=your-client-secret
ICONSCOUT_DOWNLOAD_DIR=optional-default-save-dir

Build:

git clone https://github.com/ReverserID/iconscout-mcp.git
cd iconscout-mcp
npm install
npm run build   # esbuild main.ts -> main.js

Claude Code:

claude mcp add iconscout -e ICONSCOUT_CLIENT_ID=xxx -e ICONSCOUT_CLIENT_SECRET=yyy -- node /path/to/iconscout-mcp/main.js

Any MCP client (stdio):

{
  "mcpServers": {
    "iconscout": {
      "command": "node",
      "args": ["/path/to/iconscout-mcp/main.js"],
      "env": {
        "ICONSCOUT_CLIENT_ID": "xxx",
        "ICONSCOUT_CLIENT_SECRET": "yyy"
      }
    }
  }
}

Tools

`search_assets`

Param	Default	Description
`query`	—	Search query
`asset`	`icon`	`icon`, `illustration`, `3d`, `lottie`, `all`
`price`	`all`	`all`, `free`, `premium`
`sort`	`relevant`	`relevant`, `latest`, `popular`, `color`
`page`	1	Result page
`limit`	10	Results per page (1–50)
`styles`	—	Comma-separated style filter

Returns name, uuid, price and preview URL per result.

`get_asset`

Item details by uuid: type, price, preview, slug, web page.

`preview_asset`

Fetches the item's PNG thumbnail and returns it as MCP image content — the agent sees the icon before spending a download credit. Lottie items return the video thumb URL instead.

`download_asset`

Param	Default	Description
`uuid`	—	Item uuid
`format`	`svg`	`svg`, `png`, `pdf`, `eps`, `ai` (icons/illustrations); `json`, `gif`, `mp4` (lottie); `fbx`, `glb`, `obj` (3d)
`saveDir`	`./iconscout-downloads`	Save directory
`fileName`	item name	File name override

Downloads via the signed CDN URL and saves to disk; returns the file path. Premium items consume API credits.

API notes

Search and item details need only Client-ID; downloads also send Client-Secret.
Endpoints: GET /v3/search, GET /v3/items/{uuid}, POST /v3/items/{uuid}/api-download.

Development

npm install
npm run build   # esbuild main.ts -> main.js
npm start

License

MIT