Remixicon MCP README

RemixIcon MCP

English | 简体中文

A Model Context Protocol (MCP) server that maps short keywords to Remix Icon names. Search with up to 20 comma-separated keywords and receive up to 5 ranked matches.

Features

• Local stdio, local Node.js Streamable HTTP, and Cloudflare Workers HTTP share one MCP SDK v2 server and search implementation.
• Uses a bundled FlexSearch index with English and Chinese icon tags; no external API or credentials are needed for search.
• Returns readable text and structured results with names, scores, categories, styles, and matched keywords.
• Scores all matching candidates before selecting the top results.
• HTTP supports current MCP and legacy 2025 Streamable HTTP clients. Modern requests receive JSON responses; legacy requests use request-scoped SSE. There is no standalone SSE endpoint or persistent session.

2.0.0 migration

Version 2.0.0 requires Node.js 20 or later for the installed CLI. The complete source-development and test workflow requires Node.js 22.12 or later; Wrangler deployment tooling requires Node.js 22 or later.

• Keep existing stdio client configurations; stdio remains the default. HTTP is opt-in through --transport http or a configured MCP URL.
• Keep reading matches[].name. Structured results also include scores, categories, styles, and matched keywords.
• The server uses MCP SDK v2. HTTP supports modern and legacy Streamable HTTP negotiation, but not the old standalone /sse transport or persistent sessions.
• Worker deployment is separate from npm publication. The existing hosted endpoint continues to report 1.2.0 until separately deployed.

See CHANGELOG.md for changes.

Quick start from source

Use Node.js 22.12 or later and pnpm for the complete source-development and test workflow. Wrangler itself requires Node.js 22 or later. The installed CLI runtime supports Node.js 20 or later.

pnpm install

# Start an HTTP server at http://127.0.0.1:3000/mcp
pnpm start:http

Keep the server running, then configure a URL-capable MCP client with http://127.0.0.1:3000/mcp. For Claude Code:

claude mcp add --transport http remix-icon http://127.0.0.1:3000/mcp

To use stdio instead:

pnpm start

CLI and configuration

With the CLI installed, stdio remains the default:

remixicon-mcp
remixicon-mcp --transport http --host 127.0.0.1 --port 3000

The same options work when running this checkout directly:

pnpm exec tsx src/index.ts --transport http --host 127.0.0.1 --port 3000

CLI options override environment variables. For Node HTTP, MCP_ALLOWED_ORIGINS optionally accepts comma-separated exact browser origins, such as https://icons.example.com,http://localhost:5173. Origins include the scheme and optional port, without a path or trailing slash. Same-origin requests and native clients without an Origin header are accepted by default; other browser origins are rejected.

The default host accepts local connections. To accept connections from other machines, explicitly set --host 0.0.0.0. This is public icon search with no authentication. If you expose it externally, configure TLS and any required access controls through your reverse proxy.

HTTP endpoints

POST /mcp requires Content-Type: application/json; request bodies are limited to 16 KiB. GET /mcp and DELETE /mcp return 405. There is no legacy /sse endpoint or persistent session requirement.

Published stdio package

The published package can be used by stdio clients:

npx -y remixicon-mcp

For Claude Desktop, add this entry to claude_desktop_config.json and restart the app:

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

For Claude Code:

claude mcp add --transport stdio remixicon -- npx -y remixicon-mcp

Cloudflare Workers

The existing hosted endpoint is RemixIcon MCP. Configure a URL-capable MCP client with that address, or use:

claude mcp add --transport http remix-icon https://remix-icon-mcp.frad.workers.dev/mcp

The HTTP implementation was deployed and verified on October 24, 2026, with Cloudflare version 1a2ca18e-d7a6-4910-ac2f-c6d318aa407e serving 100% of traffic. Real MCP clients passed modern (2026-07-28) and legacy (2025-11-25) protocol negotiation, tool discovery, search, and concurrent calls. The reported server version is 1.2.0; the deployed MCP SDK is 2.3.0. This records the previous deployment; it is not updated automatically when release source changes.

Use the endpoint in an MCP client. Opening /mcp in a browser sends GET and returns 405 as expected; use /health for a browser health check. Future local edits do not update the hosted service until deployment:

pnpm dev       # Local Worker preview
pnpm run deploy # Publish to Cloudflare Workers

Tool: search_icons

Input: keywords, a nonempty string of up to 200 characters containing up to 20 comma-separated keywords. Use short keywords rather than sentences.

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

Successful responses include readable content and structuredContent. The output schema is shared by all transports:

{
  guidance: string;
  matches: Array<{
    name: string;
    score: number;
    category: string;
    style: string;
    matchedKeywords: string[];
  }>;
}

matches contains zero to five items. matches[].name remains available to existing clients; the additional fields describe ranking and matched catalog tokens. Invalid keyword input returns a tool error. Tool annotations mark the search as read-only and idempotent.

Project structure

bin/run.cjs                    CLI launcher
src/cli/                       CLI options and process lifecycle
src/bootstrap/                 Dependency wiring and shared search index
src/domain/                    Icon entities and keyword parser
src/application/               Search use case and repository port
src/infrastructure/            FlexSearch repository and data adapter
src/interface/mcp/             Shared SDK v2 tool registration
src/interface/http/            Shared HTTP routes and request checks
src/data/tags.json             Bundled Remix Icon metadata
worker/src/index.ts            Cloudflare HTTP entry point
wrangler.jsonc                 Cloudflare configuration
tests/                         Unit, transport, and integration tests

Development

pnpm start        # Node stdio server
pnpm start:http   # Node HTTP server
pnpm typecheck    # Node and Worker TypeScript checks
pnpm test         # Run unit and local integration suites once
pnpm test:watch   # Watch tests during development
pnpm run test:e2e:docker # Check the hosted HTTP MCP from Docker
pnpm lint         # Biome lint with auto-fix
pnpm format       # Biome formatting
pnpm build        # Build validation

The Docker command runs nine HTTP MCP cases against https://remix-icon-mcp.frad.workers.dev/mcp using a Linux client: modern and legacy negotiation, discovery, searches, no matches, invalid input recovery, concurrent requests, client isolation, and HTTP guards. Set MCP_E2E_URL to test another deployment. It uses locked dependencies, copies no host credentials or modules, and removes its test container after the run. Each run saves report.json and runtime.json in a separate directory under .e2e/docker-http/. These live checks are separate from pnpm test.

src/data/tags.json is bundled metadata from the official RemixIcon catalog. To refresh it, update the file from that source, run tests and type checks, and review the changes before publishing a package or deploying a Worker. The server treats this metadata as read-only at runtime.

License

MIT