# @vigi-p/lucide-mcp

`lucide-mcp` is a local Model Context Protocol (MCP) server for searching [Lucide](https://lucide.dev/) 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](#what-it-does)
- [Installation](#installation)
- [Usage](#usage)
- [CLI](#cli)
- [Uninstalling](#uninstalling)
- [Dictionary Cache](#dictionary-cache)
- [License](#license)
- [Contributing](#contributing)
- [Third-Party Licenses](#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.
```bash
pnpm add -g @vigi-p/lucide-mcp
```

### Codex

```bash
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.
```json
{
  "<server-name>": {
    "command": "lucide-mcp",
    "args": [],
    "env": {}
  }
}
```

### Cursor

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

```json
{
  "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

```bash
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.
    ```bash
    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](https://github.com/lucide-icons/lucide) `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](./LICENSE).

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for development workflow and PR guidelines.

## Third-Party Licenses

Dependency licenses are tracked in [THIRD_PARTY_LICENSES.md](./THIRD_PARTY_LICENSES.md).

To regenerate the file after dependency changes:

```bash
pnpm licenses:update
```

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