Skip to main content
Glama
oli799

lucide-svg-mcp

by oli799
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

lucide-svg-mcp

An MCP server that provides Lucide icons as SVG.

This server lets MCP clients (for example Claude, Cline, or Codex) easily:

  • list all icons,

  • search icons by name or keywords,

  • retrieve the full SVG source of a specific icon.

Features

  • Uses icons from the lucide-static npm package.

  • Tools:

    • list_icons

    • search_icons

    • retrieve_icon

  • Built-in caching for faster performance:

    • icon name cache,

    • icon file path cache,

    • SVG content cache.

  • Verbose error messages when input is invalid or an icon cannot be resolved.

  • Covered by tests (vitest).

Related MCP server: Lucide Icons MCP

Requirements

  • Node.js 18+

  • npm

Running

The server uses stdio MCP transport, so your MCP client should launch it with:

npx -y lucide-svg-mcp@latest

Claude Code example

{
  "mcpServers": {
    "lucide-svg": {
      "command": "npx",
      "args": ["-y", "lucide-svg-mcp@latest"]
    }
  }
}

Cursor example

{
  "mcpServers": {
    "lucide-svg": {
      "command": "npx",
      "args": ["-y", "lucide-svg-mcp@latest"]
    }
  }
}

Codex-style TOML example:

[mcp_servers.lucide-svg]
command = "npx"
args = ["-y", "lucide-svg-mcp@latest"]

Available Tools

list_icons

Description: lists available Lucide icons with pagination.

Input:

  • limit (optional): max icons per page, default 100, max 1000

  • offset (optional): zero-based start index, default 0

Response includes pagination metadata:

  • total: total number of icons

  • count: icon count in this page

  • limit

  • offset

  • hasMore

  • nextOffset

search_icons

Description: searches Lucide icons by name or keywords.

Input:

  • query (required): search text

retrieve_icon

Description: retrieves the full SVG source for an icon.

Input:

  • name (required): icon name (for example alarm-clock)

Development

Run tests:

npm test

Run tests with coverage:

npm run test:coverage

Watch mode:

npm run test:watch

Project Structure

  • index.js: CLI bootstrap entrypoint.

  • src/server.js: MCP server creation and tool registration.

  • src/icons.js: icon logic, search, retrieve, caching.

  • tests/icons.unit.test.mjs: unit tests.

  • tests/server.integration.test.mjs: MCP server integration tests.

  • tests/index.bootstrap.test.mjs: CLI/bootstrap behavior tests.

License

  • Project: MIT

  • Lucide: ISC

Available Tools

3 tools
list_iconsB

Lists available Lucide icons with pagination.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum icons per page (1-1000).
offsetNoZero-based start index for pagination.

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals pagination support but omits other behaviors like ordering, response shape, defaults, or whether the result is a full enumeration of all icon names.

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?

A single sentence with no filler. The key operation and pagination detail are front-loaded, making it quick to parse and understand.

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

Completeness3/5

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

For a straightforward listing tool with only two query parameters, the description is minimally sufficient. However, it lacks any explanation of the return value or relationship to sibling tools, and with no output schema, an agent gets no further context to understand what a successful response looks like.

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

Parameters3/5

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

Schema description coverage is 100%, with clear descriptions for limit and offset. The description adds nothing beyond the schema, so the baseline score of 3 applies.

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

Purpose4/5

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

The description uses the verb 'Lists' with a specific resource, 'available Lucide icons', and mentions pagination. This makes the core purpose clear and differentiates it from retrieval of a single icon, though it does not explicitly distinguish itself from search_icons.

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

Usage Guidelines2/5

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

The description gives no guidance on when to use this tool versus search_icons or retrieve_icon. It only states what the tool does, not when to prefer it, leaving the agent to infer based on the tool name.

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

retrieve_iconA

Retrieves the source of the icon in SVG format.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesIcon name

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations provided, the description carries the behavioral disclosure burden. It does state that the result is the icon source in SVG format, but it does not clarify whether the response is raw SVG markup, a URL, or a file object, nor how unknown or invalid icon names are handled.

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?

A single, front-loaded sentence with no filler. It communicates action, target, and format efficiently, and every word earns its place.

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

Completeness3/5

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

Adequate for a simple one-parameter retrieval tool, but incomplete without an output schema or more precise return-format details. The agent is left to guess what 'source in SVG format' means concretely and how icon names should be specified.

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

Parameters3/5

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

Schema description coverage is 100%, and the only parameter, 'name', already has a clear 'Icon name' description. The tool description adds no further semantic detail about naming conventions, accepted formats, or possible values, so the schema remains the primary source of parameter meaning.

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 names a specific action ('Retrieves'), a specific resource ('the icon'), and a distinguishing output trait ('source ... in SVG format'). This plainly separates it from siblings list_icons and search_icons, which operate over icon collections rather than fetching a single icon's source.

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

Usage Guidelines2/5

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

No guidance is given on when to choose this tool over list_icons or search_icons. There are no exclusions, prerequisites, or alternative-selection cues, so the agent must infer usage from the tool name and sibling context.

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

search_iconsA

Searches for Lucide icons by name or keywords.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query

TDQS

A3.5/5.0
Behavior3/5

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

No annotations are provided, so the description carries the burden. It conveys that matching is by name or keywords but does not disclose result format, number of results, ordering, or whether partial matches are allowed. The read-only nature is implied by 'searches' but not explicit.

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?

A single, front-loaded sentence with no filler. It efficiently communicates the core purpose.

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?

For a simple one-parameter search tool, the description is fairly complete. It lacks explicit return-value details, but the absence of an output schema and the low complexity reduce the need. The gap is the missing sibling differentiation, which is covered under usage guidelines.

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?

The schema already documents the query parameter 100%, so the baseline is 3. The description adds semantic value by clarifying that the query can be a name or keywords, which is beyond the generic 'Search query'.

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

Purpose4/5

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

States a clear verb ('Searches') and resource ('Lucide icons') along with the matching basis ('by name or keywords'). It distinguishes from sibling tools by implying search semantics versus list/retrieve, though it does not name them explicitly.

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

Usage Guidelines2/5

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

Provides no guidance on when to use this tool versus list_icons or retrieve_icon. An agent cannot tell whether to search first or call retrieve_icon directly if an ID is known.

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.

  1. 3 tool updatesv1.0.0
    • First observedlist_icons
    • First observedretrieve_icon
    • First observedsearch_icons
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: listing all icons, searching by name/keyword, and retrieving a specific icon's SVG source. There is no meaningful overlap that would cause an agent to select the wrong tool.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: list_icons, search_icons, retrieve_icon. The naming is predictable and uniform.

Tool Count5/5

Three tools is a well-scoped size for an icon library MCP server. Each tool provides essential functionality without unnecessary bloat or missing essentials.

Completeness5/5

For an icon retrieval service, listing, searching, and fetching SVG source cover the full lifecycle of icon access. There are no obvious dead ends or missing operations that would hinder an agent.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

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
    12
    4
    MIT

  • Hugeicons

    xiaobenyang-com
    A
    license
    B
    quality
    D
    maintenance
    Hugeicons MCP Server is a TypeScript based server that provides integrated tools and resources for the Hugeicons icon library, supporting icon search, retrieval, and usage guides for multiple platforms.
    5
    2
    Apache 2.0

  • nucleo-mcp

    julianallchin
    F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that provides Claude with direct access to local Nucleo icon libraries for searching, previewing, and exporting icons. It enables users to retrieve raw SVG source code, generate PNG previews, and export icons as vector PDFs directly from the Nucleo SQLite database.
    8
    -