Which integrations are available for this server?

Enables searching and retrieving icons from the Bootstrap Icons library. Enables searching and retrieving icons from the Octicons library, GitHub's official icon set. Enables searching and retrieving icons from the Lucide library.

How do I use Icon MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Icon MCP Server find a home icon from Bootstrap" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Icon MCP Server

by agentic-ph

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

Icon MCP Server

A powerful Model Context Protocol (MCP) server that provides unified search capabilities across multiple icon libraries with fuzzy search, intelligent caching, and comprehensive filtering options.

🚀 Features

Multi-Library Support: Search across multiple icon libraries simultaneously
Fuzzy Search: Advanced search with typo tolerance using Fuse.js
Intelligent Caching: Fast response times with smart caching strategies
Comprehensive Filtering: Filter by library, style, category, tags, and more
NPM Package Integration: Automatic icon library management via NPM packages
TypeScript: Full type safety and excellent developer experience
MCP Protocol: Standard Model Context Protocol for seamless integration

Related MCP server: Scira AI MCP Server

📦 Supported Icon Libraries

Bootstrap Icons - Official open source SVG icon library for Bootstrap
Feather - Beautiful open source icons
Octicons - GitHub's icon library
Tabler Icons - Free and open source icons

🛠️ Installation

NPM Package

npm install -g icon-mcp

From Source

git clone https://github.com/your-org/icon-mcp.git
cd icon-mcp
npm install
npm run build

Build Icon Index

# Build icon indices from NPM packages
npm run build-icons

🚀 Quick Start

As MCP Server

# Start the MCP server
npm start

Configuration

The server can be configured via environment variables:

# Cache configuration
CACHE_TTL=300000          # Cache TTL in milliseconds (default: 5 minutes)
CACHE_MAX_SIZE=1000       # Maximum cache entries (default: 1000)

# Search configuration
DEFAULT_SEARCH_LIMIT=50   # Default search result limit
FUZZY_THRESHOLD=0.3       # Default fuzzy search threshold

# Logging
LOG_LEVEL=info           # Logging level (error, warn, info, debug)

🔌 Configuration for MCP Clients

Claude Desktop

Add the icon MCP server to your Claude Desktop configuration:

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

{
  "mcpServers": {
    "icon-search": {
      "command": "npx",
      "args": ["icon-mcp"],
      "env": {
        "CACHE_TTL": "300000",
        "DEFAULT_SEARCH_LIMIT": "50",
        "LOG_LEVEL": "info"
      }
    }
  }
}

VS Code MCP Extension

Configure the MCP extension in VS Code settings:

{
  "mcp.servers": [
    {
      "name": "icon-search",
      "command": "npx",
      "args": ["icon-mcp"],
      "cwd": "${workspaceFolder}",
      "env": {
        "CACHE_TTL": "300000",
        "DEFAULT_SEARCH_LIMIT": "50"
      }
    }
  ]
}

Local Development Setup

For development with a local build:

{
  "mcpServers": {
    "icon-search-dev": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/icon-mcp",
      "env": {
        "NODE_ENV": "development",
        "LOG_LEVEL": "debug",
        "CACHE_TTL": "60000"
      }
    }
  }
}

Docker Configuration

Using the Docker image:

{
  "mcpServers": {
    "icon-search-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env",
        "CACHE_TTL=300000",
        "--env",
        "LOG_LEVEL=info",
        "icon-mcp:latest"
      ]
    }
  }
}

Environment Variables for Client Configuration

Configure the server behavior through environment variables:

Variable	Description	Default	Example
`CACHE_TTL`	Cache time-to-live in milliseconds	`300000`	`600000`
`CACHE_MAX_SIZE`	Maximum number of cached entries	`1000`	`2000`
`DEFAULT_SEARCH_LIMIT`	Default number of search results	`50`	`100`
`FUZZY_THRESHOLD`	Default fuzzy search threshold (0.0-1.0)	`0.3`	`0.5`
`LOG_LEVEL`	Logging verbosity	`info`	`debug`
`NODE_ENV`	Environment mode	`production`	`development`

Connection Verification

After configuring your MCP client, verify the connection:

Check Server Status: The server should appear in your MCP client's server list
Test Basic Tool: Try the list_libraries tool to verify connectivity
Check Logs: Look for connection messages in the client logs

Troubleshooting

Common Issues

Server Not Starting

# Check if the package is installed
npm list -g icon-mcp

# Reinstall if needed
npm install -g icon-mcp

Permission Errors

# On Unix systems, ensure proper permissions
chmod +x $(which icon-mcp)

Icon Index Missing

# Build the icon index
cd /path/to/icon-mcp
npm run build-icons

Debug Mode

Enable debug logging for troubleshooting:

{
  "mcpServers": {
    "icon-search": {
      "command": "npx",
      "args": ["icon-mcp"],
      "env": {
        "LOG_LEVEL": "debug",
        "NODE_ENV": "development"
      }
    }
  }
}

Connection Testing

Test the server manually:

# Start the server directly
npx icon-mcp

# Or with debug output
LOG_LEVEL=debug npx icon-mcp

Advanced Configuration

Custom Icon Libraries

Configure additional icon libraries by setting up the icon index:

# Add custom libraries to package.json dependencies
npm install custom-icon-library

# Rebuild the icon index
npm run build-icons

Performance Tuning

For high-performance scenarios:

{
  "env": {
    "CACHE_TTL": "1800000",
    "CACHE_MAX_SIZE": "5000",
    "DEFAULT_SEARCH_LIMIT": "100",
    "FUZZY_THRESHOLD": "0.2"
  }
}

Memory Optimization

For memory-constrained environments:

{
  "env": {
    "CACHE_MAX_SIZE": "500",
    "DEFAULT_SEARCH_LIMIT": "25",
    "NODE_OPTIONS": "--max-old-space-size=512"
  }
}

📖 API Reference

Available Tools

`search_icons`

Search for icons by name across all or specific libraries with fuzzy matching.

Parameters:

query (string, required): Search term for icon names
libraries (string[], optional): Specific libraries to search in
fuzzy (boolean, optional): Enable fuzzy search (default: true)
limit (number, optional): Maximum results to return (default: 10)
threshold (number, optional): Fuzzy search threshold 0.0-1.0 (default: 0.3)
includeScore (boolean, optional): Include match scores (default: true)

Example:

{
  "query": "home",
  "libraries": ["bootstrap-icons", "feather"],
  "fuzzy": true,
  "limit": 20,
  "threshold": 0.3
}

Response:

{
  "query": "home",
  "results": [
    {
      "item": {
        "name": "house",
        "library": "bootstrap-icons",
        "tags": ["house", "home", "building"],
        "style": "regular",
        "path": "node_modules/bootstrap-icons/icons/house.svg",
        "categories": ["navigation"],
        "size": "16x16"
      },
      "score": 0.0
    }
  ],
  "totalResults": 15,
  "searchType": "fuzzy",
  "executionTime": 45,
  "libraries": ["bootstrap-icons", "feather"]
}

`get_icon`

Get detailed information about a specific icon.

Parameters:

id (string, required): Unique identifier of the icon
library (string, required): Library name where the icon is located

Example:

{
  "id": "house",
  "library": "bootstrap-icons"
}

`list_libraries`

Get a list of all available icon libraries.

Parameters: None

Response:

{
  "libraries": ["bootstrap-icons", "feather", "octicons", "lucide", "tabler-icons"],
  "count": 5
}

`get_library_info`

Get detailed information about a specific library.

Parameters:

library (string, required): Name of the library

Response:

{
  "name": "bootstrap-icons",
  "displayName": "Bootstrap Icons",
  "description": "Official open source SVG icon library for Bootstrap",
  "version": "1.11.3",
  "iconCount": 1800,
  "categories": ["navigation", "communication", "media", "ui"],
  "styles": ["regular"],
  "isAvailable": true
}

`search_by_category`

Find icons by category or tag with fuzzy matching.

Parameters:

category (string, required): Category name to search for
libraries (string[], optional): Specific libraries to search in
fuzzy (boolean, optional): Enable fuzzy search (default: true)
limit (number, optional): Maximum results to return (default: 10)

🏗️ Architecture

Core Components

src/
├── index.ts                 # Main MCP server entry point
├── providers/               # Icon provider implementations
│   ├── icon-provider.interface.ts
│   ├── base-npm-provider.ts
│   ├── heroicons.provider.ts
│   ├── bootstrap-icons.provider.ts
│   ├── feather.provider.ts
│   ├── octicons.provider.ts
│   ├── lucide.provider.ts
│   ├── simple-icons.provider.ts
│   └── tabler-icons.provider.ts
├── services/               # Core services
│   ├── search.service.ts   # Unified search service
│   └── cache.service.ts    # Caching service
├── tools/                  # MCP tools
│   └── index.ts           # Icon search tools
├── types/                  # TypeScript type definitions
│   └── index.ts
└── utils/                  # Utility functions
    └── errors.ts

Provider System

The provider system allows easy addition of new icon libraries:

export abstract class IconProvider {
  abstract initialize(): Promise<void>;
  abstract searchIcons(query: string, options?: FuseSearchOptions): Promise<FuseResult<Icon>[]>;
  abstract getIcon(id: string): Promise<Icon | null>;
  abstract getAllIcons(): Promise<Icon[]>;
  abstract getInfo(): Promise<IconLibrary>;
}

Search Service

The search service provides unified search across all providers:

Fuzzy Search: Powered by Fuse.js with configurable thresholds
Caching: Intelligent caching with TTL and LRU eviction
Filtering: Advanced filtering by library, style, category, and tags
Performance: Optimized for fast response times

🧪 Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run integration tests
npm run test:integration

# Run performance tests
npm run test:performance

🔧 Development

Setup Development Environment

git clone https://github.com/your-org/icon-mcp.git
cd icon-mcp
npm install

# Install icon library dependencies
npm install

# Build the project
npm run build

# Start in development mode
npm run dev

Adding New Icon Libraries

Add the library as an NPM dependency:

npm install new-icon-library

Create a provider class extending BaseNpmProvider:

export class NewLibraryProvider extends BaseNpmProvider {
  constructor() {
    super('new-library', 'New Library', '1.0.0', 'new-icon-library', ['icons/*.svg']);
  }

  protected getDescription(): string {
    return 'Description of the new library';
  }

  protected getSourceUrl(): string {
    return 'https://github.com/library/icons';
  }

  protected getLicense(): string {
    return 'MIT';
  }
}

registry.register(new NewLibraryProvider());

Add the library configuration to scripts/build-index.js:

'new-icon-library': {
  name: 'new-library',
  displayName: 'New Library',
  description: 'Description of the new library',
  sourceUrl: 'https://github.com/library/icons',
  license: 'MIT',
  iconPaths: ['icons/*.svg'],
  styles: ['regular'],
}

Code Style

TypeScript: Strict mode enabled
ESLint: Configured with TypeScript rules
Prettier: Consistent code formatting
Husky: Pre-commit hooks for quality checks

📊 Performance

Search Speed: < 100ms for most queries with caching
Memory Usage: Efficient memory management with LRU caching
Scalability: Supports thousands of icons across multiple libraries
Fuzzy Search: Optimized Fuse.js configuration for best performance

🔒 Security

Input Validation: All inputs validated with Zod schemas
Output Sanitization: Safe handling of SVG content
Error Handling: Comprehensive error handling without information leakage
Dependencies: Regular security audits and updates

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Write tests for new features
Follow TypeScript best practices
Update documentation for API changes
Ensure all CI checks pass

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Fuse.js for powerful fuzzy search capabilities
Model Context Protocol for the standard protocol
All the icon library maintainers for their amazing work

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Wiki

Made with ❤️ for the developer community

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/agentic-ph/icon-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server