Claude Desktop Configuration

To use this server with Claude Desktop, add the following configuration to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "remix-icon": {
      "command": "npx",
      "args": ["-y", "remixicon-mcp"]
    }
  }
}

After saving the configuration file, completely quit and restart Claude Desktop for the changes to take effect.

Claude Code Configuration

Add as Marketplace Plugin

Install directly from GitHub as a marketplace plugin:

# In Claude Code, add the marketplace
/plugin marketplace add Remix-Design/remixicon-mcp

This provides:

• Automatic installation and updates
• Complete plugin metadata and versioning
• Keywords and categorization for discovery
• Rich descriptions and author information
• Full integration with Claude Code's plugin ecosystem

Manual Configuration (Alternative)

Alternatively, add the following to your project's .claude/settings.json:

{
  "mcp": {
    "servers": {
      "remix-icon": {
        "command": "npx",
        "args": ["-y", "remixicon-mcp"]
      }
    }
  }
}

After adding the configuration, restart Claude Code for the changes to take effect.

Available Tools

The server communicates over stdio using JSON-RPC 2.0 via the official @modelcontextprotocol/sdk and exposes a single tool:

• search_icons – requires a keywords string (comma-separated, up to 20 keywords). Always returns top 5 results.

Example Tool Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_icons",
    "arguments": {
      "keywords": "layout, grid, design"
    }
  }
}

The server returns human-readable summaries plus structured metadata with the top 5 icons that matched the supplied keywords.

Project Structure

.
├── bin/
│   └── run.cjs                     # CLI entry point for npx execution
├── src/
│   ├── cli/                        # CLI runner implementation
│   ├── bootstrap/                  # Dependency wiring for Clean Architecture boundaries
│   ├── domain/                     # Icon entities and keyword parser
│   ├── application/                # Search use case orchestrating validation and ranking
│   ├── infrastructure/search/      # FlexSearch-backed repository implementation
│   ├── interface/mcp/              # MCP server built with @modelcontextprotocol/sdk
│   └── data/tags.json              # Remix Icon tags for search functionality
├── tests/                          # Vitest suites covering parser and use case behaviour
├── .claude-plugin/
│   └── marketplace.json            # Marketplace metadata for Claude Code plugin discovery
├── package.json                    # pnpm-friendly manifest and scripts
└── tsconfig.json                   # Strict TypeScript configuration with Node typings

Implementation Notes

• Keywords are parsed with Unicode-aware boundaries, supporting up to 20 comma-separated keywords while rejecting sentence-style inputs.
• Enhanced detection differentiates between keyword lists (with delimiters) and natural language sentences (space-separated phrases).
• FlexSearch indexes icon names, tags, usage, and categories; field weights plus token matches drive deterministic scores.
• Fixed top-5 results provide focused, relevant matches without configuration complexity.
• The application layer combines parser validation, repository queries, and response formatting so the interface only handles transport concerns.
• MCP responses include natural-language guidance and machine-readable matches so LLM clients can choose exactly one icon.
• CLI runner enables standalone execution via npx or global installation for easy integration.

Development Scripts

pnpm typecheck   # Strict TypeScript check (tsc --noEmit)
pnpm test        # Run Vitest suites
pnpm exec biome check --write --unsafe   # Format + fix code with Biome

License

MIT License