mcp-iconify/README.md

Model Context Protocol (MCP) server for accessing the Iconify API - search, retrieve, and customize icons from 100+ icon sets

# MCP Iconify Server

[![npm version](https://badge.fury.io/js/mcp-iconify.svg)](https://www.npmjs.com/package/mcp-iconify)
[![PR Validation](https://github.com/nc-helix/mcp-iconify/actions/workflows/pr.yml/badge.svg)](https://github.com/nc-helix/mcp-iconify/actions/workflows/pr.yml)

A fast MCP (Model Context Protocol) server for accessing the Iconify API, built with Bun and TypeScript.

## Features

- Search icons across all Iconify collections
- Retrieve SVG data with customization options
- List and explore icon collections
- Built with Bun for maximum performance

## Installation

### From NPM (Recommended)

Install the MCP server globally via npm:

```bash
npm install -g mcp-iconify
```

The `mcp-iconify` command will be available globally after installation.

### From Source

For development or if you want the latest unreleased features:

```bash
# Clone the repository
git clone https://github.com/nc-helix/mcp-iconify.git
cd mcp-iconify

# Install dependencies
bun install

# Build the project
bun run build

# Link the package globally
bun link

# Ensure ~/.bun/bin is in your PATH
export PATH="$HOME/.bun/bin:$PATH"
```

**Important:** After making any code changes, you must rebuild and re-link:

```bash
bun run build && bun link
```

### Using Docker

If you prefer containerized deployment:

```bash
# Build the Docker image
docker build -t mcp-iconify .

# Run the MCP server
docker run -i mcp-iconify
```

## Setting up with MCP Clients

### Claude Code

After installing and linking the package:

```bash
claude mcp add -s user iconify -- mcp-iconify
```

### Cline

Add to your Cline MCP settings (usually in VS Code settings):

```json
{
  "cline.mcpServers": {
    "iconify": {
      "command": "mcp-iconify"
    }
  }
}
```

### Gemini CLI

Add to your `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "iconify": {
      "command": "mcp-iconify"
    }
  }
}
```

### Generic MCP Configuration

For other MCP clients, use this configuration pattern:

```json
{
  "name": "iconify",
  "command": "mcp-iconify"
}
```

### Docker-based MCP Configuration

If using Docker instead of a local installation:

```json
{
  "name": "iconify",
  "command": "docker",
  "args": ["run", "-i", "mcp-iconify"]
}
```

For Claude Code with Docker:

```bash
claude mcp add -s user iconify -- docker run -i mcp-iconify
```

## Development

```bash
# Run in development mode with hot reload
bun run dev

# Run tests
bun test

# Run linting
bun run lint

# Type checking
bun run typecheck
```

## Configuration

Create a `.env` file based on `.env.example`:

```env
NODE_ENV=development
LOG_LEVEL=info
ICONIFY_API_URL=https://api.iconify.design
CACHE_TTL=3600
REQUEST_TIMEOUT=5000
MAX_SEARCH_RESULTS=100
DEFAULT_SEARCH_LIMIT=25
```

## Available Tools

- **iconify_list_collections** - List all available icon collections with pagination support
  - Parameters:
    - `offset` (optional): Starting index for pagination (default: 0)
    - `limit` (optional): Maximum number of collections to return, max 100 (default: 50)

- **iconify_search** - Search for icons across all collections
  - Parameters:
    - `query`: Search query string
    - `limit` (optional): Maximum number of results to return, max 999 (default: 64)
    - `start` (optional): Starting position for pagination (default: 0)
    - `prefixes` (optional): Array of collection prefixes to limit search to

- **iconify_get_icon** - Get SVG data for a specific icon with customization options
  - Parameters:
    - `prefix`: Collection prefix (e.g., "mdi", "fa")
    - `name`: Icon name within the collection
    - `width` (optional): Custom width for the SVG
    - `height` (optional): Custom height for the SVG
    - `color` (optional): Custom color for the icon
    - `rotate` (optional): Rotation in degrees (0, 90, 180, 270)
    - `flip` (optional): Flip direction ("horizontal", "vertical", or "both")

- **iconify_get_collection_info** - Get detailed information about a specific collection
  - Parameters:
    - `prefix`: Collection prefix to get information for

## Release Management

### Version Management

The version number is stored in `package.json` and serves as the single source of truth. Git tags should always match the package.json version.

### Creating Releases

#### Option 1: Simple Release (Manual Version Control)

When you want to release the current version in package.json:

```bash
# Release current version
./scripts/release.sh
```

This script:
- Reads the version from package.json
- Creates a matching git tag (e.g., v0.1.0)
- Pushes the tag to trigger GitHub Actions
- Displays monitoring links

#### Option 2: Version Bump + Release (Automated)

When you want to increment the version and release:

```bash
# Patch release (0.1.0 -> 0.1.1)
./scripts/bump-version.sh patch

# Minor release (0.1.0 -> 0.2.0)
./scripts/bump-version.sh minor

# Major release (0.1.0 -> 1.0.0)
./scripts/bump-version.sh major
```

This script:
- Updates the version in package.json
- Commits the version change
- Creates and pushes the git tag
- Triggers the release automatically

#### Manual Release Process

If you prefer manual control:

1. Update version in `package.json`
2. Commit the version change
3. Create and push a git tag:
   ```bash
   git tag v0.1.0
   git push origin v0.1.0
   ```

### Release Workflow

When a version tag is pushed, GitHub Actions automatically:
1. Runs tests and builds the project
2. Publishes to NPM registry
3. Creates a GitHub release
4. Links everything together

Monitor releases at: https://github.com/nc-helix/mcp-iconify/actions

## License

MIT