google_search_images
Search Google for images using a query, specifying country, language, location, or time period. Retrieve results in bulk for data analysis or research purposes via the Serper MCP Server.
Instructions
Search Google for results
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gl | No | The country to search in, e.g. us, uk, ca, au, etc. | |
| hl | No | The language to search in, e.g. en, es, fr, de, etc. | |
| location | No | The location to search in, e.g. San Francisco, CA, USA | |
| num | No | The number of results to return, max is 100 | |
| page | No | The page number to return, first page is 1 | |
| q | Yes | The query to search for | |
| tbs | No | The time period to search in, e.g. d, w, m, y |
Input Schema (JSON Schema)
{
"properties": {
"gl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The country to search in, e.g. us, uk, ca, au, etc.",
"title": "Gl"
},
"hl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The language to search in, e.g. en, es, fr, de, etc.",
"title": "Hl"
},
"location": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The location to search in, e.g. San Francisco, CA, USA",
"title": "Location"
},
"num": {
"default": 10,
"description": "The number of results to return, max is 100",
"maximum": 100,
"title": "Num",
"type": "integer"
},
"page": {
"anyOf": [
{
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": 1,
"description": "The page number to return, first page is 1",
"title": "Page"
},
"q": {
"description": "The query to search for",
"title": "Q",
"type": "string"
},
"tbs": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The time period to search in, e.g. d, w, m, y",
"title": "Tbs"
}
},
"required": [
"q"
],
"title": "SearchRequest",
"type": "object"
}
Implementation Reference
- src/serper_mcp_server/core.py:14-17 (handler)Handler function that constructs the specific Serper API endpoint for 'google_search_images' (https://google.serper.dev/images) based on the tool enum value and performs the API request via fetch_json.async def google(tool: SerperTools, request: BaseModel) -> Dict[str, Any]: uri_path = tool.value.split("_")[-1] url = f"https://google.serper.dev/{uri_path}" return await fetch_json(url, request)
- src/serper_mcp_server/core.py:25-40 (helper)Helper function that sends the POST request to the Serper API with the request payload and API key, returning the JSON response.async def fetch_json(url: str, request: BaseModel) -> Dict[str, Any]: payload = request.model_dump(exclude_none=True) headers = { 'X-API-KEY': SERPER_API_KEY, 'Content-Type': 'application/json' } ssl_context = ssl.create_default_context(cafile=certifi.where()) connector = aiohttp.TCPConnector(ssl=ssl_context) timeout = aiohttp.ClientTimeout(total=AIOHTTP_TIMEOUT) async with aiohttp.ClientSession(connector=connector, timeout=timeout) as session: async with session.post(url, headers=headers, json=payload) as response: response.raise_for_status() return await response.json()
- Pydantic schema for input validation of google_search_images tool, inheriting from BaseRequest (q, gl, location, hl, page). Defines additional fields tbs (time filter) and num (number of results). Used in registration.class SearchRequest(BaseRequest): tbs: Optional[str] = Field( None, description="The time period to search in, e.g. d, w, m, y" ) num: str = Field( "10", pattern=r"^([1-9]|[1-9]\d|100)$", description="The number of results to return, max is 100 (integer value as string)", )
- src/serper_mcp_server/server.py:25-38 (registration)Dictionary mapping SerperTools enum values to their corresponding Pydantic request schemas. 'google_search_images' is mapped to SearchRequest for input parsing.google_request_map = { SerperTools.GOOGLE_SEARCH: SearchRequest, SerperTools.GOOGLE_SEARCH_IMAGES: SearchRequest, SerperTools.GOOGLE_SEARCH_VIDEOS: SearchRequest, SerperTools.GOOGLE_SEARCH_PLACES: AutocorrectRequest, SerperTools.GOOGLE_SEARCH_MAPS: MapsRequest, SerperTools.GOOGLE_SEARCH_REVIEWS: ReviewsRequest, SerperTools.GOOGLE_SEARCH_NEWS: SearchRequest, SerperTools.GOOGLE_SEARCH_SHOPPING: ShoppingRequest, SerperTools.GOOGLE_SEARCH_LENS: LensRequest, SerperTools.GOOGLE_SEARCH_SCHOLAR: AutocorrectRequest, SerperTools.GOOGLE_SEARCH_PATENTS: PatentsRequest, SerperTools.GOOGLE_SEARCH_AUTOCOMPLETE: AutocorrectRequest, }
- src/serper_mcp_server/server.py:41-60 (registration)MCP list_tools handler that registers all Google search tools, including 'google_search_images', with name, generic description, and inputSchema from the mapped request class.@server.list_tools() async def list_tools() -> List[Tool]: tools = [] for k, v in google_request_map.items(): tools.append( Tool( name=k.value, description="Search Google for results", inputSchema=v.model_json_schema(), ), ) tools.append(Tool( name=SerperTools.WEBPAGE_SCRAPE, description="Scrape webpage by url", inputSchema=WebpageRequest.model_json_schema(), )) return tools