# lordicon-mcp

An MCP (Model Context Protocol) server that lets AI agents search, preview, and generate embed code for [Lordicon](https://lordicon.com) animated icons.

## Features

- **Search icons** — Find icons by keyword with filtering by family, style, and premium status
- **Preview icons** — Get visual SVG previews that AI agents can actually see
- **Browse families** — List all available icon families and styles
- **Generate embed code** — Get ready-to-paste HTML, React, or web component code

## Setup

### 1. Get a Lordicon API Key

Sign up at [lordicon.com](https://lordicon.com) and get your API key from the dashboard.

### 2. Add to your MCP client

#### Claude Code

```bash
claude mcp add lordicon -e LORDICON_API_KEY=your-api-key-here -- npx -y github:roandegraaf/lordicon-mcp
```

#### Other MCP Clients

Add the server to your client's MCP configuration:

```json
{
  "mcpServers": {
    "lordicon": {
      "command": "npx",
      "args": ["-y", "github:roandegraaf/lordicon-mcp"],
      "env": {
        "LORDICON_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Tools

### `search_icons`

Search for icons by keyword.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query |
| `family` | string | No | Filter by family |
| `style` | string | No | Filter by style |
| `premium` | boolean | No | Filter by premium status |
| `page` | number | No | Page number (default: 1) |
| `per_page` | number | No | Results per page (default: 20, max: 50) |

### `get_icon_preview`

Get a visual SVG preview of a specific icon.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `family` | string | Yes | Icon family |
| `style` | string | Yes | Icon style |
| `index` | number | Yes | Icon index from search results |

### `list_families`

List all icon families with their styles and icon counts. No parameters.

### `get_embed_code`

Generate embed code for an icon.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `family` | string | Yes | Icon family |
| `style` | string | Yes | Icon style |
| `index` | number | Yes | Icon index from search results |
| `format` | string | No | `html`, `react`, or `web-component` (default: `html`) |
| `trigger` | string | No | Animation trigger (default: `hover`) |
| `size` | number | No | Size in pixels (default: 64) |
| `colors` | string | No | Color customization |

## Development

```bash
npm install
npm run build
```

Test with the MCP Inspector:

```bash
LORDICON_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js
```

## License

MIT