Image Scraper

A Python web scraper that retrieves images for a given search query. Supports DuckDuckGo Images and Google Maps place photos — no API key required, and every result carries the credit/attribution you need to safely reuse the image.

Features

• Three scraping scripts:
  • image_scraper_selenium.py (Selenium DuckDuckGo) — recommended; returns the real image URL plus full source attribution
  • image_scraper_maps.py (Selenium Google Maps) — place photo scraper with photographer attribution
  • image_scraper.py (BeautifulSoup DuckDuckGo) — fast fallback that only returns URL + alt text
• MCP server (image_scraper_mcp_server.py) exposing both search_images and search_maps_images tools
• Credit & attribution built-in — every result includes the publisher domain, source page URL, article title, and image dimensions so you can credit the image instead of just receiving a proxied redirect
• Configurable number of images, headless mode, and error handling

Credit & Attribution

Reusing images from search results requires credit. Both scrapers are built to give you what you need:

Tool	What you get for credit
search_images (DDG)	source_domain, source_url, title, source_favicon_url, width, height — the real image URL, with DDG's iu/?u= redirector unwrapped
search_maps_images (Google Maps)	author (the Google Maps contributor's name) and author_profile_url — the photographer's profile URL

Suggested credit format:

• DuckDuckGo results: Image: {title or alt} — {source_domain} ({source_url}). If source_domain or source_url is missing for a result, treat that entry as low-attribution and prefer a different one.
• Google Maps results with an author: Photo by {author} ({author_profile_url}).
• Google Maps results with no author (official place photos): Image: {Place Name} via Google Maps or Source: Google Maps.

Installation

1. Install Python dependencies:

uv sync

2. Make sure you have Google Chrome installed (required for Selenium). Selenium 4+ automatically manages ChromeDriver, no manual installation needed.

Usage

Selenium DuckDuckGo (recommended)

uv run python image_scraper_selenium.py "cute cats" 5

Prints a JSON payload with attribution per image:

{
  "query": "cute kittens",
  "source": "duckduckgo",
  "count": 2,
  "images": [
    {
      "url": "https://tse3.mm.bing.net/th/id/OIP.6ytt01A4fK8ToB7he6XJegHaFD?pid=Api",
      "alt": "Cute Kittens Playing With Yarn Free Stock Photo - Public Domain Pictures",
      "title": "Cute Kittens Playing With Yarn Free Stock Photo - Public Domain Pictures",
      "source_url": "https://www.publicdomainpictures.net/en/view-image.php?image=588007&picture=cute-kittens-playing-with-yarn",
      "source_domain": "publicdomainpictures.net",
      "source_favicon_url": "https://external-content.duckduckgo.com/ip3/www.publicdomainpictures.net.ico",
      "width": 1920,
      "height": 1309,
      "ddg_proxied_url": "https://external-content.duckduckgo.com/iu/?u=..."
    }
  ]
}

The url is the real image URL (DDG's external-content.duckduckgo.com/iu/?u= redirector is unwrapped). ddg_proxied_url is kept for reference. Width and height are read from the dimensions overlay on the result tile.

When called through the MCP server, the same data is rendered as human-readable text that includes a Credit: line per result, plus the source page title and dimensions:

Found 2 images for 'cute kittens':

1. https://tse3.mm.bing.net/th/id/OIP.6ytt01A4fK8ToB7he6XJegHaFD?pid=Api
   Credit: publicdomainpictures.net (https://www.publicdomainpictures.net/en/view-image.php?image=588007&picture=cute-kittens-playing-with-yarn)
   Title: Cute Kittens Playing With Yarn Free Stock Photo - Public Domain Pictures
   Dimensions: 1920 × 1309
   Alt: Cute Kittens Playing With Yarn Free Stock Photo - Public Domain Pictures

2. https://tse1.mm.bing.net/th/id/OIP.So-qlqEv3QwuZpL4cOY-PwHaHa?pid=Api
   Credit: wallpaperaccess.com (https://wallpaperaccess.com/cute-cats-and-kittens)
   Title: Cute Cats and Kittens Wallpapers - Top Free Cute Cats and Kittens ...
   Dimensions: 2560 × 1600
   Alt: Cute Cats and Kittens Wallpapers - Top Free Cute Cats and Kittens ...

Google Maps place photos

uv run python image_scraper_maps.py "Eiffel Tower" 5

{
  "query": "Joe's Pizza NYC",
  "source": "google_maps",
  "count": 3,
  "images": [
    {
      "url": "https://lh3.googleusercontent.com/...",
      "author": "Mary van Lutsenburg Maas",
      "author_profile_url": "https://www.google.com/maps/contrib/118270766331517021243"
    }
  ]
}

By default, the scraper prefers photos with visible author attribution and falls back to the place's official photo strip when fewer attributed photos are available — so you always get num_images results if any exist. Attributed photos are returned first, then official ones fill the remaining slots. Pass require_attribution: true to disable the fallback and only get attributed photos.

BeautifulSoup DuckDuckGo (no Selenium, fast)

uv run python image_scraper.py "cute cats" 5

Lightweight fallback. Only returns the proxied image URL and the alt text — no source attribution. Use this only when you need a fast scrape and don't need to credit the result.

Specifying the number of images

All scrapers accept an optional second argument for the result count (1–50, default 5):

uv run python image_scraper_selenium.py "sports cars" 10
uv run python image_scraper_maps.py "Eiffel Tower" 8
uv run python image_scraper.py "golden retriever puppy" 5

MCP Server

image_scraper_mcp_server.py exposes two tools:

Tool	Use for	Returns
search_images	General image search (DDG)	Text output with Credit:, Title:, Dimensions:, Alt: per result
search_maps_images	Place photos (Google Maps)	JSON output with author and author_profile_url per photo

search_images parameters

• query (required): Search query
• num_images (optional, default 5, range 1–50): Number of results
• headless (optional, default true): Run Chrome headless

search_maps_images parameters

• query (required): Place name (e.g. "Eiffel Tower", "Joe's Pizza NYC")
• num_images (optional, default 5, range 1–50): Number of photos
• headless (optional, default true): Run Chrome headless
• require_attribution (optional, default false): If true, only return photos with visible author attribution. If false (default), prefer attributed photos but fall back to the place's official photo strip when fewer attributed photos are available.

See MCP_SETUP.md for installing the server as a Docker-based MCP tool for Claude Desktop or other MCP clients.

Tests

.venv/bin/python -m unittest discover -s tests

87 tests cover both scrapers and the MCP server, with all browser interactions stubbed so they run in seconds without Chrome or network access:

• tests/test_image_scraper_ddg.py — DDG URL decoding, dimensions parser, tile attribution, MCP text formatting
• tests/test_image_scraper_maps.py — Google Maps review-photo extraction, fallback, MCP JSON formatting

Notes

• DuckDuckGo is generally more scraper-friendly than Google.
• The Selenium DuckDuckGo scraper is more reliable than the BeautifulSoup version and returns proper attribution.
• Some images may be low resolution or thumbnails; check width and height before reuse.
• Respect robots.txt and the terms of service of DuckDuckGo and Google Maps.
• Reuse of copyrighted images may require permission from the publisher; the attribution fields tell you who to ask.

License

MIT License — feel free to use and modify as needed.