lucabzt/google-image-search-mcp-server

Google Image Search MCP Server

An MCP (Model Context Protocol) server that provides advanced Google Image Search with parallel image information retrieval.

Features

• 🔍 Google Custom Search Integration: Search images using Google's API
• ⚡ Parallel Processing: Uses threading to fetch image dimensions and alt text simultaneously
• 📏 Smart Filtering: Automatically discards images with invalid dimensions
• 🎨 Advanced Search Parameters: Supports image type, size, color, and more
• 🚀 High Performance: Multi-threaded architecture for fast results
• 📝 Formatted Output: Returns clean, readable formatted strings

Installation

1. Install dependencies:

pip install -r requirements.txt

2. Set up environment variables: Create a .env file in the same directory with your Google Custom Search credentials:

GCS_DEVELOPER_KEY=your_google_api_key_here
GCS_CX=your_custom_search_engine_id_here

Getting Google Custom Search Credentials

1. Get API Key:

   • Go to Google Cloud Console
   • Enable "Custom Search API"
   • Create credentials (API Key)

2. Get Custom Search Engine ID (CX):

   • Go to Programmable Search Engine
   • Create a new search engine
   • Select "Search the entire web"
   • Copy the Search Engine ID (CX)

Usage

Running the Server

python image_search_mcp_server.py

The server runs using stdio transport, which is the standard for MCP servers.

Using with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "google-image-search": {
      "command": "python",
      "args": ["/absolute/path/to/image_search_mcp_server.py"],
      "env": {
        "GCS_DEVELOPER_KEY": "your_api_key",
        "GCS_CX": "your_cx_id"
      }
    }
  }
}

Using with Other MCP Clients

The server exposes one tool: search_images

Tool: search_images

Parameters:

• q (required): Search query string
• img_type (optional): Image type filter
  • Options: clipart, face, lineart, stock, photo, animated, imgTypeUndefined
• img_size (optional): Image size filter
  • Options: huge, icon, large, medium, small, xlarge, xxlarge, imgSizeUndefined
• img_dominant_color (optional): Dominant color filter
  • Options: black, blue, brown, gray, green, orange, pink, purple, red, teal, white, yellow, imgDominantColorUndefined
• img_color_type (optional): Color type filter
  • Options: color, gray, mono, trans, imgColorTypeUndefined

Returns: Formatted string with structure:

Image Search Results for: 'coffee'
Found 20 images, 18 valid
Search time: 1.23s
Processing time: 3.45s
Total time: 4.68s

================================================================================

Image 1:
  URL: https://example.com/coffee.jpg
  Referrer: https://example.com/page
  Dimensions: 1920x1080
  Alt text: A cup of coffee

Image 2:
  URL: https://example.com/coffee2.jpg
  Referrer: https://example.com/page2
  Dimensions: 1280x720

...

Error Handling: Returns "Image Search currently not available" for any error conditions

Example Usage in Claude

Once connected, you can ask Claude:

Search for images of "sunset over mountains" with large size

Find clipart images of "coffee cup"

Search for red, xlarge photos of "sports cars"

Architecture

Threading Strategy

The server uses a two-level threading approach for maximum performance:

1. Level 1 - Image Processing: Up to 10 images processed simultaneously
2. Level 2 - Info Retrieval: For each image, 2 parallel threads fetch:
   • Image dimensions (from image header)
   • Alt text (from referrer page)

Performance

• Search Time: ~1-2 seconds (Google API)
• Processing Time: ~3-5 seconds for 20 images (parallel)
• Total Time: ~4-7 seconds for complete results

Error Handling

• Images with invalid dimensions (width or height = -1) are automatically discarded
• Network timeouts are handled gracefully
• Failed alt text retrievals don't block the result (alt_text field is simply omitted)

Implementation Details

Key Functions

1. get_image_info_fast(url):

   • Reads only the first 24KB of the image (header)
   • Extracts dimensions using imagesize library
   • Returns -1 for both dimensions on error

2. get_image_alt_text(image_url, referrer_url):

   • Fetches the referrer HTML page
   • Parses with BeautifulSoup
   • Finds matching <img> tag and extracts alt attribute
   • Returns None if not found

3. process_single_image(image_url, referrer_url):

   • Spawns 2 threads for parallel fetching
   • Combines results
   • Returns None if image should be discarded

4. search_images(...) (MCP Tool):

   • Main entry point
   • Performs Google Image Search
   • Spawns multiple threads for parallel image processing
   • Returns JSON results

Testing

Test the server manually:

from image_search_mcp_server import search_images

# Search for coffee images
result = search_images(q="coffee", img_size="large")
print(result)

# Output will be a formatted string like:
# Image Search Results for: 'coffee'
# Found 20 images, 18 valid
# ...

Or use the provided test script:

python test_image_search.py

Troubleshooting

"No images found"

• Check your Google API credentials
• Verify the search query
• Ensure your Custom Search Engine is set to search the entire web

Slow performance

• Check your network connection
• Some referrer pages may be slow to load
• Consider reducing the number of concurrent workers

Missing alt text

• Many images don't have alt text set
• This is normal and expected
• The field will be omitted from results if not found

License

MIT License - Feel free to use and modify as needed.

Contributing

Contributions welcome! Please feel free to submit issues or pull requests.