Skip to main content
Glama
willlaiwk

icon-search-mcp

by willlaiwk
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

icon-search-mcp

An MCP server that finds open-source, commercially-usable icons and returns direct SVG download links. Runs locally in Docker over stdio.

Icons come from the Iconify public API — 300,000+ icons across 231 open-source icon sets, each with machine-readable SPDX licence metadata.

Design rationale, recorded decisions, and known limitations live in docs/design.md.

How it works

Iconify's search index is keyword-based, not semantic — ?query=fast deployment returns zero results. So the natural-language step lives in the calling model, not in this server:

User: "find me an icon that represents fast deployment"
  │
  ▼  the host model translates the description into keywords
search_icons({ keywords: ["rocket", "deploy", "upload"] })
  │
  ├─ one parallel Iconify query per keyword
  ├─ merge and dedupe, tracking which keywords each icon matched
  ├─ drop icons whose set fails the licence policy
  └─ rank: most keywords matched first, then Iconify's relevance order

The tool description instructs the host model to do that translation and to retry with broader keywords when a search comes back empty.

Related MCP server: icogenie-mcp

Setup

docker build -t icon-search-mcp .

Then register it with your MCP client:

{
  "mcpServers": {
    "icon-search": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "icon-search-mcp"]
    }
  }
}

For Claude Code: claude mcp add icon-search -- docker run --rm -i icon-search-mcp

Tool: search_icons

Parameter

Type

Default

Description

keywords

string[] (1–5)

required

Concrete English icon keywords, most relevant first

limit

number (1–64)

12

Maximum icons to return

license_policy

enum

permissive

See below

Each result carries the icon id, set name, author, full licence details, and both a download_url (serves Content-Disposition: attachment) and a preview_url.

{
  "id": "material-symbols:rocket-launch",
  "name": "rocket-launch",
  "set": "Material Symbols",
  "author": { "name": "Google", "url": "https://github.com/google/material-design-icons" },
  "license": {
    "spdx": "Apache-2.0",
    "title": "Apache 2.0",
    "url": "https://github.com/google/material-design-icons/blob/master/LICENSE",
    "attribution_required": false,
    "copyleft": false
  },
  "download_url": "https://api.iconify.design/material-symbols/rocket-launch.svg?download=1",
  "preview_url": "https://api.iconify.design/material-symbols/rocket-launch.svg",
  "matched_keywords": ["rocket", "launch"]
}

Licence policies

Policy

Allows

Reach

permissive (default)

MIT, Apache-2.0, ISC, BSD-3-Clause, CC0-1.0, Unlicense, OFL-1.1, MPL-2.0

~224k icons

permissive_plus_attribution

above + CC-BY-4.0, CC-BY-3.0 — you must credit the author

~291k icons

all

above + copyleft (GPL-*, CC-BY-SA-*) — share-alike terms apply to derivatives

~315k icons

NonCommercial sets (cbi, ps) are excluded under every policy, including all.

Licence data is reported as published by each icon set; verify it against the linked LICENSE file before shipping an icon in a product. This server surfaces licence terms, it does not give legal advice.

Development

npm install
npm test    # builds, then runs offline unit tests against fixtures
npm start   # run the server directly on stdio, without Docker

src/licenses.ts and src/search.ts are pure functions with no I/O; src/iconify.ts is the only module that touches the network.

Available Tools

1 tool
search_iconsSearch open-licensed iconsA

Search 300,000+ open-source, commercially-usable icons and return direct SVG download links.

The underlying index is KEYWORD-BASED, NOT SEMANTIC. You must translate the user's description into 1-5 concrete English icon keywords yourself. Prefer common, concrete nouns ('rocket', 'cart', 'bell') over abstract phrases ('fast deployment', 'user engagement') — abstract phrases return zero results. If a search comes back empty, retry once with broader or more common keywords.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum icons to return.
keywordsYes1-5 concrete English icon keywords, most relevant first. Single nouns work best.
license_policyNopermissive: MIT/Apache-2.0/ISC/BSD-3/CC0/Unlicense/OFL/MPL only, no attribution duty. permissive_plus_attribution: also allows CC-BY, which requires crediting the author. all: also allows copyleft (GPL, CC-BY-SA). NonCommercial sets are excluded under every policy.permissive

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It clearly discloses that the index is KEYWORD-BASED, NOT SEMANTIC, and warns that abstract phrases will fail, plus a retry recommendation. This is meaningful behavioral context beyond the raw schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the main purpose, then immediately follows with critical operational guidance. All sentences are purposeful and concise, with no redundant filler, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no output schema, the description covers the core aspects: what it does, how to query, and what it returns (SVG download links). However, it could be more explicit about the exact response structure (e.g., array of objects with a 'url' field), which would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value by giving concrete examples of ideal keywords ('rocket', 'cart', 'bell') and contrasting them with abstract phrases ('fast deployment'), enriching the 'keywords' parameter semantics beyond the schema's terse description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Search 300,000+ open-source, commercially-usable icons and return direct SVG download links' with a specific verb ('Search'), a clear resource (icons), and a concrete result type (direct SVG links). This makes the tool's purpose immediately obvious and differentiates it even without siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage guidance: 'You must translate the user's description into 1-5 concrete English icon keywords yourself' and advises preferring concrete nouns over abstract phrases, which return zero results. It also gives a retry strategy for empty searches, making the intended invocation clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev0.1.0
    • First observedsearch_icons
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.6/5.0
Disambiguation5/5

With only one tool, there is no possibility of confusion or overlap between tools. The single 'search_icons' tool has a clear, singular purpose, making disambiguation trivial.

Naming Consistency5/5

The tool name 'search_icons' follows a clear verb_noun snake_case pattern, which is self-consistent and descriptive. Even though there is only one tool, its naming is unambiguous and aligns with common conventions.

Tool Count3/5

The server has only one tool, which feels thin even for a specialized icon-search service. While the core search functionality is covered, the absence of additional operations like fetching by name or browsing categories leaves the server at a borderline level of usefulness.

Completeness4/5

For the stated purpose of keyword-based icon search, the tool covers the essential search-and-download workflow effectively. Minor gaps include the inability to directly retrieve an icon by known name or ID, and no support for browsing or filtering by category, but these are not critical for basic usage.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • PickAPIcon MCP

    Leee62
    A
    license
    B
    quality
    D
    maintenance
    MCP server that allows FE/UI/Designers to retrieve SVG icons via the Iconify API by simply asking LLMs rather than manually searching websites.
    3
    30
    4
    MIT

  • icogenie-mcp

    albertnahas
    A
    license
    Not graded
    quality
    C
    maintenance
    AI-powered SVG icon generation MCP server. Generate production-ready SVG icons from text descriptions with customizable styles, sizes, and themes.
    44
    6
    MIT

  • lucide-svg-mcp

    oli799
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that provides Lucide icons as SVG, allowing clients to list, search, and retrieve icons by name.
    3
    21
    MIT

  • mcp-icon

    hustcc
    A
    license
    A
    quality
    D
    maintenance
    A Model Context Protocol (MCP) server for semantic SVG icon search. Generate infographic SVG icons by keyword — over 100,000 icons with semantic search support.
    1
    20
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/willlaiwk/icon-search-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server