@vigi-p/lucide-mcp

lucide-mcp is a local Model Context Protocol (MCP) server for searching Lucide icon names by keyword tags.

It builds a local dictionary from Lucide icon metadata and exposes a search-icons tool over stdio.

• What It Does
• Installation
• Usage
• CLI
• Uninstalling
• Dictionary Cache
• License
• Contributing
• Third-Party Licenses

What It Does

1. Starts an MCP server over stdio.
2. Registers a search-icons tool.
3. Token matches keywords against icon names and tags by score.
4. Returns best-matching icon names.

Installation

Install the package.

pnpm add -g @vigi-p/lucide-mcp

Codex

codex mcp add <server-name> lucide-mcp

Zed

In the Agent panel, go to Settings-->Model Context Protocol (MCP) Servers->Add Server->Add Custom Server and add the following in the Local tab.

{
  "<server-name>": {
    "command": "lucide-mcp",
    "args": [],
    "env": {}
  }
}

Cursor

Go to Cursor Settings->Tools & MCP->Add New MCP and add lucide-mcp to "mcpServers"

{
  "mcpServers": {
    "<server-name>": {
      "command": "lucide-mcp",
      "args": [],
      "env": {}
    },
    // Other MCPs...
  }
}

Usage

Some prompt like Show me sample code for a navbar in astro with lucide icons. Use lucide-mcp.

CLI

lucide-mcp [options]

Options:
  -h, --help                Show this help message
  -v, --version             Print the current version
  -c, --create-dictionary   Create the icons dictionary

Uninstalling

1. Remove the MCP from your IDE/agent. Eg: codex mcp remove <server-name>.
2. Remove the package.

   pnpm remove -g @vigi-p/lucide-mcp

3. Delete the ~/.lucide-mcp folder.

Dictionary Cache

On first run (or with --refresh), the project fetches icon metadata from the Lucide repo's icons directory and writes a local dictionary to ~/.lucide-mcp/dictionary.json.

A temporary cache directory is used during fetch and then removed (~/.lucide-mcp/cache).

License

This project is licensed under the MIT License. See LICENSE.

Contributing

See CONTRIBUTING.md for development workflow and PR guidelines.

Third-Party Licenses

Dependency licenses are tracked in THIRD_PARTY_LICENSES.md.

To regenerate the file after dependency changes:

pnpm licenses:update

The generator script uses pnpm licenses list --json and writes a grouped package/license inventory.