no setup, no code

Ask your AI for the right icon.

Say what the icon is for, then click Claude, ChatGPT, Gemini, Perplexity or Grok. We copy a ready brief that points it to our skill file and open it for you. It comes back with the best-fit icon, two alternatives, the right style and code or steps for your app.

1Say what the icon is for
2Pick your assistant
3We copy a brief and open it

What’s the icon for? optional — or tell the assistant later

The assistant opens in a new tab, searches with icons and replies with the best fit and how to use it. Nothing is sent to us: the prompt only tells your assistant where to read about with icons (llms.txt and the skill). Gemini can’t pre-fill the message: paste it with Ctrl+V (⌘V on a Mac).

Five things to ask

Every brief starts by sending the assistant to our skill file, so it searches the real library and never invents icon names. You pick the job; we write the brief.

Find the right icon
Next to every search box, and here
You type“a button that clears the cart in my grocery app”
The best fit with a one-line reason, up to two alternatives, the right style for where it goes, and code or steps for your app.
Code it for my app
On every icon page
You type“the delete button in my React table”
Paste-ready code for your stack, the size and colour, the exact aria-label and tooltip text, and hover, focus, active and disabled states.
Build a matching set
On every icon page
You type“the toolbar of my notes app”
The 4 to 8 icons that belong next to this one, all in one style and size, with why each is there and anything the library doesn’t cover.
Is this the right icon?
On every icon page
You type“remove item, for shoppers in Japan”
An honest verdict, what people will actually read it as, cultural or ambiguity issues, and better options from the library if there are any.
Use it in my slides or doc
On every icon page and app guide
You type“a pricing slide in Google Slides”
Which file to grab (copy image, SVG or PNG and what size), how to insert, recolour and resize it in your app, layout tips, and the matching step-by-step guide.

Add with icons to your AI tool

Coding agents work best with the real thing: connect with icons once and your assistant searches by meaning, uses the right package for your stack and never invents an icon name. Pick your tool.

Claude Code

Skill in .claude/skills plus the MCP server, so Claude Code searches icons by meaning and pastes the right import.

MCP server: .mcp.json
Agent skill: .claude/skills/with-icons/SKILL.md

Checked against code.claude.com on 2026-10-01

Step by step

One command fastest
Run in your project. It copies the skill to .claude/skills/with-icons/ and adds the server to .mcp.json. Add --global for every project.
Terminal
```
npx withicons init claude-code
```
Or add the server with Claude Code's own CLI
Remote, no install. Use --scope user for all projects or --scope project to share it through .mcp.json.
Terminal
```
claude mcp add --transport http withicons https://withicons.com/mcp
```
Run it locally instead
The same server over stdio (Node 18+).
Terminal
```
claude mcp add --transport stdio withicons -- npx -y @withicons/mcp
```
Check
Type /mcp in Claude Code to see the withicons tools, and ask for "an icon for deleting things, in React".

Prefer to edit the config yourself?

Remote · recommended

.mcp.json

{
  "mcpServers": {
    "withicons": {
      "type": "http",
      "url": "https://withicons.com/mcp"
    }
  }
}

Local · npx

.mcp.json

{
  "mcpServers": {
    "withicons": {
      "command": "npx",
      "args": [
        "-y",
        "@withicons/mcp"
      ]
    }
  }
}

OpenAI Codex

For the Codex CLI, IDE extension and app: the skill in .agents/skills and the server in config.toml.

MCP server: ~/.codex/config.toml
Agent skill: .agents/skills/with-icons/SKILL.md

Checked against developers.openai.com on 2026-10-01

Step by step

One command fastest
Copies the skill to .agents/skills/with-icons/ and adds [mcp_servers.withicons] to .codex/config.toml (Codex reads project config in trusted projects). Add --global to use ~/.codex/config.toml and ~/.agents/skills.
Terminal
```
npx withicons init codex
```
Or use the Codex CLI
Streamable HTTP, no install.
Terminal
```
codex mcp add withicons --url https://withicons.com/mcp
```
Run it locally instead
stdio via npx (Node 18+).
Terminal
```
codex mcp add withicons -- npx -y @withicons/mcp
```
IDE extension
The CLI, IDE extension and app share config.toml. In the extension: gear menu › MCP servers › Add server › Streamable HTTP, then restart the extension.

Prefer to edit the config yourself?

Remote · recommended

~/.codex/config.toml

[mcp_servers.withicons]
url = "https://withicons.com/mcp"

Local · npx

~/.codex/config.toml

[mcp_servers.withicons]
command = "npx"
args = ["-y", "@withicons/mcp"]

Cursor

One click adds the server to Cursor. The skill goes in .agents/skills, which Cursor loads automatically.

MCP server: .cursor/mcp.json
Agent skill: .agents/skills/with-icons/SKILL.md

Checked against cursor.com on 2026-10-01

Step by step

One click
Use the Add to Cursor button. Cursor opens and asks you to confirm the withicons server.
Add to Cursor Add to Cursor (local, npx)
Or one command fastest
Copies the skill to .agents/skills/with-icons/ and adds the server to .cursor/mcp.json. Add --global for ~/.cursor/mcp.json.
Terminal
```
npx withicons init cursor
```

Or edit mcp.json yourself

Project: .cursor/mcp.json. Everywhere: ~/.cursor/mcp.json.

Remote · recommended

.cursor/mcp.json

{
  "mcpServers": {
    "withicons": {
      "url": "https://withicons.com/mcp"
    }
  }
}

Local · npx

.cursor/mcp.json

{
  "mcpServers": {
    "withicons": {
      "command": "npx",
      "args": [
        "-y",
        "@withicons/mcp"
      ]
    }
  }
}

OpenCode

Adds a remote MCP entry to opencode.json and the skill to .agents/skills, which OpenCode discovers on its own.

MCP server: opencode.json
Agent skill: .agents/skills/with-icons/SKILL.md

Checked against opencode.ai on 2026-10-01

Step by step

One command fastest
Copies the skill to .agents/skills/with-icons/ and adds "withicons" under "mcp" in opencode.json. Add --global for ~/.config/opencode/opencode.json and ~/.agents/skills.
Terminal
```
npx withicons init opencode
```

Or edit opencode.json

OpenCode merges project and global config. opencode mcp add also walks you through it interactively.

Remote · recommended

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "withicons": {
      "type": "remote",
      "url": "https://withicons.com/mcp",
      "enabled": true
    }
  }
}

Local · npx

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "withicons": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@withicons/mcp"
      ],
      "enabled": true
    }
  }
}

Check
Run opencode mcp list.
Terminal
```
opencode mcp list
```

Lovable

Connect the remote server as a chat connector and import the skill from GitHub. No install.

Open Lovable Connectors

Checked against docs.lovable.dev on 2026-10-01

Step by step

Add the MCP server
Open Connectors, choose + (top right) › MCP server. Name: with icons. URL: https://withicons.com/mcp. Authentication: none. Available on all plans; each teammate connects their own.
URL
```
https://withicons.com/mcp
```
Add the skill (owners and admins)
Workspace settings › Skills › Add › Import from GitHub, and paste this link. It is shared with every project in the workspace.
URL
```
https://github.com/withevergrow/withicons/tree/main/skills/with-icons
```

Or add project knowledge

Project settings › Knowledge (up to 10,000 characters). Paste the note below.

Project knowledge

Icons: use the "with icons" library (https://withicons.com, MIT). Read https://withicons.com/skill/SKILL.md before adding icons. Find names with the withicons MCP server (search_icons) or https://withicons.com/api/search?q=<words>; never invent an icon name. React: npm i @withicons/react, then import { Home } from '@withicons/react'. Use the line style for UI, solid for active states, and one style per region. Icon-only buttons need an aria-label.

Claude Desktop

Add the remote server as a custom connector, or run it locally from claude_desktop_config.json. Upload the skill as a zip.

MCP server: claude_desktop_config.json
Agent skill: with-icons.zip

Checked against support.claude.com on 2026-10-01

Step by step

Remote connector
Customize › Connectors › + › Add custom connector, then paste the URL. Free plans allow one custom connector.
URL
```
https://withicons.com/mcp
```
Or run it locally fastest
This command adds the npx server to claude_desktop_config.json (Claude menu › Settings › Developer › Edit Config). Quit and reopen Claude afterwards.
Terminal
```
npx withicons init claude-desktop
```
Upload the skill
Make the zip, then go to Customize › Skills › + › Create skill › Upload a skill. Code execution must be on.
Terminal
```
npx withicons skill --zip
```

Prefer to edit the config yourself?

Local · npx

claude_desktop_config.json

{
  "mcpServers": {
    "withicons": {
      "command": "npx",
      "args": [
        "-y",
        "@withicons/mcp"
      ]
    }
  }
}

VS Code (Copilot)

Install the server in one click for Copilot agent mode. The skill goes in .agents/skills, which VS Code loads.

MCP server: .vscode/mcp.json
Agent skill: .agents/skills/with-icons/SKILL.md

Checked against code.visualstudio.com on 2026-10-01

Step by step

One click
Use Install in VS Code. VS Code asks you to confirm and trust the server.
Install in VS Code Install in VS Code Insiders
Or one command fastest
Copies the skill to .agents/skills/with-icons/ and adds the server to .vscode/mcp.json.
Terminal
```
npx withicons init vscode
```

Or the VS Code CLI (user profile)

Adds the local server to your user mcp.json.

Terminal

code --add-mcp "{\"name\":\"withicons\",\"command\":\"npx\",\"args\":[\"-y\",\"@withicons/mcp\"]}"

Prefer to edit the config yourself?

Remote · recommended

.vscode/mcp.json

{
  "servers": {
    "withicons": {
      "type": "http",
      "url": "https://withicons.com/mcp"
    }
  }
}

Local · npx

.vscode/mcp.json

{
  "servers": {
    "withicons": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@withicons/mcp"
      ]
    }
  }
}

Windsurf

Windsurf is now Devin Desktop. Its Cascade agent reads MCP servers from your user mcp_config.json and skills from .agents/skills.

MCP server: ~/.config/devin/mcp_config.json
Agent skill: .agents/skills/with-icons/SKILL.md

Checked against docs.devin.ai on 2026-10-01

Step by step

One command fastest
Copies the skill to .agents/skills/with-icons/ and adds the server to your user mcp_config.json (~/.config/devin/, or %APPDATA%\devin\ on Windows; an existing ~/.codeium/windsurf/mcp_config.json is updated too).
Terminal
```
npx withicons init windsurf
```

Or edit mcp_config.json

Cascade has no one-click install. Remote servers use serverUrl. Refresh the MCP list afterwards.

Remote · recommended

~/.config/devin/mcp_config.json

{
  "mcpServers": {
    "withicons": {
      "serverUrl": "https://withicons.com/mcp"
    }
  }
}

Local · npx

~/.config/devin/mcp_config.json

{
  "mcpServers": {
    "withicons": {
      "command": "npx",
      "args": [
        "-y",
        "@withicons/mcp"
      ]
    }
  }
}

See what your agent gets back

This runs the same search engine as the MCP server, right here in your browser, and shows the same JSON the tool returns. Type what an agent might ask for.

Query

What it found

Tool call

Response

The MCP server

The Model Context Protocol lets AI apps use tools. Add with icons once and your assistant can search, resolve and fetch icons on its own.

Remote · Streamable HTTP

https://withicons.com/mcp

Local · stdio

npx -y @withicons/mcp

Add it to your app

Exact, checked setup for Claude Code, Codex, Cursor, OpenCode, Lovable, Claude Desktop, VS Code and Windsurf is in Add with icons to your AI tool above. Any other client that speaks MCP: give it the remote URL, or this local config.

mcp.json

{
  "mcpServers": {
    "withicons": {
      "command": "npx",
      "args": [
        "-y",
        "@withicons/mcp"
      ]
    }
  }
}

On Windows, if npx isn’t found, use "command": "cmd", "args": ["/c", "npx", "-y", "@withicons/mcp"].

Tools

search_icons{ query, limit?, style?, category?, format? }
Find icons by meaning: “throw away” finds trash. Ranked and typo-tolerant. Each result comes with why it matched, a ready-to-paste snippet (React unless you pass format) and a link. Default limit: 10.
get_icon{ name, style?, format?, size?, color? }
One icon as paste-ready code. name can be an alias (“delete” → trash). format: svg | react | vue | svelte | angular | solid | html-class | web-component | data-uri (default svg). color replaces currentColor in svg and data-uri.
animate_icon{ name, trigger?, preset?, to?, effect?, style?, format? }
Paste-ready animation code for the optional @withicons/motion package: loop, hover, once, inview or swap (play turns into pause), in HTML, React, Vue, Svelte, Solid, Angular or a web component.
export_icon{ name, style?, format?, size?, background?, palette?, motion?, out_dir? }
Files, not code: SVG, PNG, PDF, PowerPoint, Word, favicons, app assets, Lottie, and animated GIF, APNG, SVG or a PowerPoint slide with the moving icon, for slides and docs. The local server (npx -y @withicons/mcp) saves them to out_dir or returns them inline; the remote one makes the vector files and answers the rest with the exact npx withicons export command.
resolve_icon{ name }
Check a guess: resolved (with the alias it came through), ambiguous (with candidates) or unknown (with the nearest names).
list_styles{}
The 20 styles, which are universal, creative or playful, and what each looks like.
list_categories{ category? }
Every category with icon counts, or, with category, every icon in that category.

Resources

Clients that read MCP resources can open any icon directly: icon://<style>/<name>.svg (for example icon://solid/home.svg), plus icon://about for an overview. Everything is bundled: no network, no API key.

Example: get_icon

Tool call

{
  "tool": "get_icon",
  "arguments": {
    "name": "delete",
    "style": "solid",
    "format": "react"
  }
}

Response

{
  "name": "trash",
  "requested": "delete",
  "title": "Trash",
  "category": "actions",
  "style": "solid",
  "format": "react",
  "size": 24,
  "code": "import { Trash as TrashSolid } from '@withicons/react/solid'\n\n<TrashSolid />",
  "url": "https://withicons.com/icons/trash.html",
  "motion": {
    "intent": "rocks on its base, then wobbles as it is filled",
    "loop": "rock",
    "hover": "wiggle",
    "alt": [
      "shake",
      "bounce"
    ],
    "swap": [
      "check (morph)",
      "trash@solid (scale)"
    ],
    "howTo": "animate_icon(name, trigger: loop|hover|once|inview|swap, format) returns paste-ready code (@withicons/motion)."
  }
}

The agent skill

A skill is a short instruction file an agent reads before it starts. Ours teaches it how to use with icons well: search by meaning, pick one style per product, use the right package for the framework, add labels for accessibility, and never invent icon names.

Read SKILL.md

Drop the folder into your agent’s skills directory (for Claude Code: .claude/skills/with-icons/).

Files for language models

No tools? Give your model these files. They’re plain text and JSON, updated with every release.

/llms.txtA short map of the project for language models: what it is, install lines, canonical imports, links./llms-full.txtEverything in one file: every icon with its description, aliases and tags. Paste it into any chat./icons.jsonMachine-readable metadata for all 500 icons: names, categories, aliases, tags, styles.

HTTP API

The same tools over plain HTTP GET, handy for scripts, bots and no-code tools. Responses are JSON, the same as the MCP tools return.

Route	Same as
`/api/search?q=&limit=&style=&category=&format=`	`search_icons`
`/api/icon/<name>?style=&format=&size=&color=`	`get_icon`. Add `&raw=1` for just the code, or use `/api/icon/<name>.svg` for an SVG image.
`/api/resolve/<name>`	`resolve_icon`
`/api/styles`	`list_styles`
`/api/categories`, `/api/categories/<category>`	`list_categories`

Request

curl "https://withicons.com/api/search?q=throw%20away&limit=2"

Response

{
  "query": "throw away",
  "style": "line",
  "count": 2,
  "results": [
    {
      "name": "trash",
      "title": "Trash",
      "category": "actions",
      "score": 119.96,
      "reason": "matched related word \"throw away\"",
      "match": {
        "field": "synonym",
        "term": "throw away",
        "typo": false,
        "kind": "exact"
      },
      "snippet": "import { Trash } from '@withicons/react'\n\n<Trash />",
      "url": "https://withicons.com/icons/trash.html"
    },
    {
      "name": "close",
      "title": "Close",
      "category": "navigation",
      "score": 45.07,
      "reason": "matched related word \"go away\"",
      "match": {
        "field": "synonym",
        "term": "go away",
        "typo": false,
        "kind": "concept"
      },
      "snippet": "import { Close } from '@withicons/react'\n\n<Close />",
      "url": "https://withicons.com/icons/close.html"
    }
  ],
  "suggestions": []
}

Request

curl "https://withicons.com/api/resolve/expand"

Response

{
  "status": "ambiguous",
  "candidates": [
    "chevron-down",
    "maximize"
  ]
}

From the terminal

Agents that run shell commands can use the CLI. Add --json for stable, machine-readable output (exit code 0 = found, 1 = not found or ambiguous, 2 = usage error).

Terminal

npx withicons search "throw away" --json
npx withicons get trash --style solid --format react
npx withicons resolve bin --json

All commands and options are on the developer page.

Ask like this

Once the server is connected, just talk normally:

Ask your AI for the right icon.

Five things to ask

Find the right icon

Code it for my app

Build a matching set

Is this the right icon?

Use it in my slides or doc

Add with icons to your AI tool

Claude Code

One command fastest

Or add the server with Claude Code's own CLI

Run it locally instead

Check

OpenAI Codex

One command fastest

Or use the Codex CLI

Run it locally instead

IDE extension

Cursor

One click

Or one command fastest

Or edit mcp.json yourself

OpenCode

One command fastest

Or edit opencode.json

Check

Lovable

Add the MCP server

Add the skill (owners and admins)

Or add project knowledge

Claude Desktop

Remote connector

Or run it locally fastest

Upload the skill

VS Code (Copilot)

One click

Or one command fastest

Or the VS Code CLI (user profile)

Windsurf

One command fastest

Or edit mcp_config.json

See what your agent gets back

The MCP server

Add it to your app

Tools

Resources

Example: get_icon

The agent skill

Files for language models

HTTP API

From the terminal

Ask like this