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

1. 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)

1. 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

1. get_image_alt_text(image_url, referrer_url):

- Fetches the referrer HTML page - Parses with BeautifulSoup - Finds matching `` tag and extracts alt attribute - Returns None if not found

1. process_single_image(image_url, referrer_url):

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

1. 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.