A1 AI engineering company GitHub
Connect the Google Custom Search MCP server to your AI agent Open source, MIT, on npm. Setup instructions for Claude, Cursor and Codex are in the repository; adoption questions — Telegram. GitHub repository Telegram

Google Custom Search: Search for images — MCP tool

Google Custom Search MCP tool: Image search through your Programmable Search Engine — results carry the image file URL, dimensions, a thumbnail and the hosting page, filterable by size, type, color and license.

Technical name: search_images

What task it solves

I want to find images on the web — by subject, size, type, color or license — from my AI session.

Runs the same Custom Search query as search with searchType=image. Each item's url is the image file itself; image.context_url is the page hosting it, alongside width/height/byte_size and a thumbnail_url with its own dimensions for previews.

When to use it

Use it to find illustrations, product photos, logos or reference images — especially with the rights filter when the image must be reusable (e.g. cc_publicdomain). It works only when the engine has Image search enabled in the engine control panel; otherwise the API answers 400.

What to provide

  • query — required.
  • Image filters, all optional: size (icon..huge), type (clipart/face/lineart/stock/photo/animated), color_type (mono/gray/color/trans), dominant_color.
  • Everything the web search accepts also works here: pagination (num, start), safe, language/country filters, site_search + site_search_filter, date_restrict, file_type (e.g. svg), rights, engine_id.

What it returns

The same normalized shape as the web search — query, total_results, page cursors and items[] — where every item additionally carries the image object (context URL, dimensions, byte size, thumbnail). mime tells the image format.

What changes in Google Custom Search

Nothing. This is a pure read; the API cannot modify anything. Each call consumes one unit of the same per-project daily quota as the web search.

Example request

Find large, transparent-background PNG or SVG icons of a paper plane with a license that allows reuse, and show thumbnails and source pages.

Errors and limitations

  • HTTP 400 with image parameters usually means the engine has Image search disabled — enable it in the control panel.
  • The same paging ceiling as web search: 10 per call, 100 per query.
  • The rights filter relies on how pages declare licenses — verify the license on the source page before using an image.
  • HTTP 429 is the daily quota or rate limit; HTTP 403 is the key or a disabled API.

Access also depends on key restrictions, quotas, and upstream API limits.

Related MCP tools

Technical details