google-images-mcp

Purpose

google-images-mcp is a hosted Model Context Protocol (MCP) server that provides a read-only Google Images tool for Claude, Cursor, Windsurf, and other MCP clients, letting AI agents reason over image search results without a browser or scraping library. It reads the Google Images results page as seen by a logged-out visitor.

Main capabilities

• Single-tool image search: run a search with a text query and get 100 results in one call.
• Filtering: supports filtering by size, color, and type via Google's own tbs filter string; combine multiple filters with commas. Examples:isz:l get large images;isz:lt,islt:2mp get images larger than 1600×1200;isz:ex,iszw:1000,iszh:1000 get images exactly 1000×1000.
• Returned fields: a results array imagesResults, each containing position、title, the linkof the page the image is on, the site name source, the thumbnailon Google CDN, the full-resolution file original , as well as originalWidth and originalHeight.
• Resources: the server exposes 5 resources, each corresponding to a parameter that accepts a fixed list of values, with URIs of the form hasdata://google_images/<parameter>. Reading resources does not consume quota, and the list can be obtained without an API key.
• No self-hosting: remote server, no container to run. If the client supports OAuth, you can add the same URL as a connector and sign in, with no key in the config file.

How to use

You need an MCP client and an API key from the HasData dashboard (create one for free, no credit card required).

The remote server URL is the same for all clients:https://mcp.hasdata.com/mcp?apis=google_images

OAuth-supporting clients (such as Claude): Settings → Connectors → Add custom connector → paste the above URL and sign in.

Config file approach: Claude Desktop only loads local (stdio) servers, so you need to connect to the remote server via a stdio launcher. The npm package @hasdata/google-images-mcp is that launcher, and it reads the key from an environment variable. Add it to claude_desktop_config.json. If you use Python instead of Node, you can use the PyPI package instead, run by uvx without manual installation.

Cursor:~/.cursor/mcp.json(all projects) or .cursor/mcp.json(a single project).

Windsurf:~/.codeium/windsurf/mcp_config.json, note that its field name is serverUrl rather than url.

VS Code: .vscode/mcp.jsonin the workspace.

Example prompts

• Find images of the Austin skyline, and give me ones wider than 1500 pixels.
• Which sites are ranking images for this product name?
• Get black-and-white photos for this query, skipping clip art and line drawings.
• Search this query from German Google and compare with US sources.
• Find images of this landmark and tell me which ones are stock photos.
• Pull the next page of results for this query.

Each call can answer the above questions because one page contains 100 results; pagination is only needed when there are more than 100.

Suitable scenarios

• Let AI agents analyze the source sites, size distribution, or type distribution of image search results.
• Filter images by size or color for asset selection.
• Compare search results across different regions (domain, gl, hl).
• Use together with other HasData APIs: one key covers all services, providing multiple sets of tools in the same connection via the apis parameter, for example pointing to ?apis=google_images,google_serp to get both at once, or pointing to mcp.hasdata.com/mcp Get the complete table of contents.

Limitations and caveats

• Only text-based queries are supported; reverse image search is not supported (reverse image search is a separate endpoint).
• original is a third-party URL and may fail, be blocked by hotlink protection, or respond slowly; it should be fetched defensively, with thumbnail(provided by the Google CDN) as a fallback.thumbnail is a real URL rather than a data URI, so displaying it still requires making a request to gstatic.com.
• One page carries 100 results rather than 10; billing is per call rather than per result.ijn starts from zero, so passing in 1 returns the second page rather than the first.
• originalWidth and originalHeight describe the original file, not the thumbnail, so local size filtering needs to read these fields.
• tbs values are defined by Google, and unrecognized values are ignored rather than rejected, so manually assembled filter strings need to be verified to confirm that the results actually narrow.
• domain、gl and hl are three independent dimensions: the domain is which Google responds, the country code is the geographic origin of the search, and the language is the interface language; changing one of them may have less impact on results than expected.
• Results that carry data also include requestMetadata.id, which can be cited when supported.
• Billing: the Google Images tool costs 10 credits per successful call, regardless of response size; non-200 responses are not billed, but successful calls with no results are still counted. The free tier provides 1,000 credits per month with no credit card required, roughly equivalent to 100 calls, and renews with the billing cycle. Paid plans start at $59 per month for 200,000 credits (20,000 calls), with the unit price decreasing as usage increases: the Starter plan is $1.48 per 1,000 calls, Basic is $0.60, and the Growth tiers are $0.41 each. Current figures are subject to the pricing page.
• Concurrency limits: the free tier allows 1 request at a time, Startup 5, Basic 15, and the Growth tiers 50 to 500. In unattended scenarios, 429 responses should be retried with backoff.
• Compared with Google's official Custom Search JSON API: the latter is a programmable search engine whose coverage is limited to the sites you configure, and it is free at low traffic and more suitable when you control the sites; this tool reads the public Google Images page. Google has not released an official Google Images MCP server; this service is maintained by HasData and is not affiliated with, endorsed by, or sponsored by Google.
• Usage restrictions: results return whatever matches the query, so a query naming a person returns images of that person, anditp:face specifically requests faces. Images of identifiable individuals are personal data, and biometric processing is subject to separate and stricter regulation in several jurisdictions, so building a face dataset requires careful evaluation. Whether an image may be downloaded, stored, or reused is a copyright issue; the fact that Google indexed the image does not mean it may be used.

Testing and licensing

test/ tests assert the tool contract, including that ?apis=google_images returns the expected single tool, that the name is unchanged, that it still requires q and includes a description, that the filtering and targeting parameters documented in the README are still in the schema, and that the key used is actually accepted (this check makes a real call to the tool and costs 10 credits). There is also a test asserting that live search results carry both original and its dimensions. The contract suite runs on a weekly schedule because the upstream tool list may change without anyone modifying this repository. The license is MIT, see LICENSE.

Others

Other HasData MCP servers: Google Search, Google Maps, Google Trends, Google Flights, Bing, DuckDuckGo, YouTube, TikTok, Instagram, Amazon, Walmart, Shopify, Yelp, Yellow Pages, Zillow, Redfin, Airbnb, Booking.com, Indeed, Glassdoor.