# lucide-svg-mcp

An MCP server that provides [Lucide](https://lucide.dev/) 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`).

## Requirements

- Node.js 18+
- npm

## Running

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

```bash
npx -y lucide-svg-mcp@latest
```

### Claude Code example

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

### Cursor example

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

### Codex-style TOML example:

```toml
[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:

```bash
npm test
```

Run tests with coverage:

```bash
npm run test:coverage
```

Watch mode:

```bash
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