OmenDilly/thiings_mcp

Thiings Icon Search MCP Server

This MCP (Model Context Protocol) server allows you to search for and download icons from the Thiings website (https://www.thiings.co/things) directly into your project. Optimized for Cursor!

Features

• Search Icons: Search for icons on the Thiings website using keywords
• Download Icons: Download specific icons by URL
• One-Click Download: Search and download the first matching icon in one command
• Automatic Organization: Icons are saved to your project directory
• Cursor Integration: Easy setup and configuration for Cursor

Quick Setup for Cursor

1. Run the setup script:

   python3 setup_cursor.py
   

2. Restart Cursor to load the MCP server

3. Start using it in Cursor chat:

   "Search for home icons on the Thiings website"
   

That's it! The setup script will automatically:

• Install all dependencies
• Configure the MCP server for Cursor
• Create usage documentation

Manual Installation

If you prefer to set it up manually:

1. Install Dependencies:

   pip install -r requirements.txt
   

2. Configure Cursor: Create or edit .cursor/mcp.json in your project:

   {
     "mcpServers": {
       "thiings-icon-search": {
         "command": "python3",
         "args": ["thiings_icon_mcp.py"],
         "cwd": ".",
         "description": "Search and download icons from the Thiings website"
       }
     }
   }
   

3. Restart Cursor to load the new MCP server

Available Tools

1. search_thiings_icons

Search for icons on the Thiings website.

Parameters:

• query (optional): Search query for finding specific icons

Example:

{
  "query": "home"
}

2. download_thiings_icon

Download a specific icon from a URL.

Parameters:

• icon_url (required): URL of the icon to download
• filename (required): Filename for the downloaded icon
• output_dir (optional): Directory to save the icon (default: current directory)

Example:

{
  "icon_url": "https://www.thiings.co/icons/home.svg",
  "filename": "home_icon.svg",
  "output_dir": "./icons"
}

3. search_and_download_icon

Search for an icon and download the first match automatically.

Parameters:

• query (required): Search query for finding the icon
• output_dir (optional): Directory to save the icon (default: current directory)

Example:

{
  "query": "settings",
  "output_dir": "./assets/icons"
}

Usage Examples

Basic Search

Use the search_thiings_icons tool to find icons related to "navigation"

Download Specific Icon

Download the icon from https://www.thiings.co/icons/user.svg and save it as "user_icon.svg"

Quick Search and Download

Search for a "hamburger menu" icon and download the first result to the ./icons directory

File Structure

thiings_mcp/
├── server.py              # Main MCP server implementation
├── requirements.txt       # Python dependencies
├── mcp_config.json       # MCP server configuration
└── README.md             # This file

Technical Details

How It Works

1. Web Scraping: The server uses aiohttp and BeautifulSoup to scrape the Thiings website
2. Icon Detection: It searches for common icon patterns using CSS selectors
3. Download Management: Icons are downloaded asynchronously and saved to the specified directory
4. Duplicate Handling: The server removes duplicate icons based on URL

Icon Detection Strategy

The server looks for icons using these CSS selectors:

• img[src*="icon"] - Images with "icon" in the src attribute
• img[alt*="icon"] - Images with "icon" in the alt text
• .icon img - Images within icon classes
• [class*="icon"] img - Images within elements with icon-related classes
• svg[class*="icon"] - SVG elements with icon classes
• .thing img - Images within "thing" elements
• [class*="thing"] img - Images within thing-related elements

Error Handling

The server includes comprehensive error handling for:

• Network failures
• Invalid URLs
• File system errors
• HTML parsing errors

Development

To test the server locally:

# Install dependencies
pip install -r requirements.txt

# Run the server (for testing)
python server.py

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is open source and available under the MIT License.

Notes

• The server respects the Thiings website's structure and may need updates if the site changes
• Downloaded icons retain their original format (PNG, SVG, etc.)
• The server creates output directories automatically if they don't exist
• Large icons are downloaded efficiently using streaming