mcp-google-custom-search
This MCP server provides read-only Google Programmable Search access for web and image searches, plus a raw Custom Search API escape hatch.
Run web searches with Google query syntax and filters for language, country, date range, site include/exclude, file type, license rights, safe search, exact/excluded/OR terms, duplicate filtering, and pagination up to 100 results.
Run image searches with the same core filters plus image-specific filters: size, image type, color type, and dominant color; results include image files, dimensions, thumbnails, and hosting page URLs.
Use
raw_requestto call any Custom Search JSON API GET path for parameters not exposed by typed tools, such asfields,lowRange/highRange,c2coff, orhq.Optionally include raw
pagemapmetadata for richer page details.Override the configured Programmable Search Engine id per call.
Perform only read-only, idempotent searches; the API has no write endpoints, and each call consumes one daily quota unit.
Provides web and image search through Google Custom Search / Programmable Search Engine, with support for filtering by language, country, date, site, paging through results, and making raw API requests.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-google-custom-search Search the web for recent articles about renewable energy trends and summarize the top three results."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Google Custom Search MCP
English | Русский
A1 Google Custom Search MCP lets an AI app search the web and images in plain language through your Programmable Search Engine. Ask for pages, narrow by language, country, date or site, page through results and pull image files with thumbnails.
It uses the Google Custom Search JSON API with your Google Cloud API key. You decide what the engine covers — a handful of sites or the entire web — and the server makes the limits of the JSON API explicit instead of implying that every search task is possible.
3 tools. Web search, image search, and a raw GET escape hatch for parameters the typed tools don't expose.
Read-only end to end. The Custom Search JSON API has no write endpoint; every tool is marked read-only and nothing here can modify data.
You control the coverage. The engine's configuration decides what gets searched; results and ranking can differ from google.com.
The key stays in a header. API-key authentication — no OAuth, no scopes; the key travels in the
X-Goog-Api-Keyheader and never appears in a URL.Not Google Search Console. It cannot report how your own site is indexed or ranked.
Start with a read-only question:
Find recent articles about passkey adoption from the last month and summarize the top three results.
Connect the server · Explore use cases · Open technical documentation
See it work in a minute
You: Find recent articles about passkey adoption, English only, from the last month.
Assistant: Runs one search through your engine and shows each result's title, link and snippet. Nothing changes — every tool is read-only.
You: Show the next page.
Assistant: Continues from the
next_startcursor and shows results 11–20 of the same query.You: Now find large press photos on the same topic.
Assistant: Switches to image search and returns image files with their dimensions, thumbnails and the pages that host them.
Related MCP server: Google Search MCP Server
Contents
Quick start
You need Node.js 20+, a Google Cloud API key with the Custom Search API enabled and a Programmable Search Engine id (cx).
Add the server to your AI app.
Ask the read-only question above.
In the app: open Settings → MCP servers, select Add server, choose STDIO, enter the command npx -y mcp-google-custom-search@latest and environment variables GOOGLE_CUSTOM_SEARCH_API_KEY, GOOGLE_CUSTOM_SEARCH_ENGINE_ID, then select Save and Restart.
From the command line:
codex mcp add google-custom-search \
--env GOOGLE_CUSTOM_SEARCH_API_KEY=your_api_key \
--env GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your_engine_id \
-- npx -y mcp-google-custom-search@latestcodex mcp listclaude mcp add \
--env GOOGLE_CUSTOM_SEARCH_API_KEY=your_api_key \
--env GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your_engine_id \
--transport stdio --scope user google-custom-search \
-- npx -y mcp-google-custom-search@latestclaude mcp listThe current official path is Settings → Extensions. For a custom desktop extension, open Advanced settings → Extension Developer → Install Extension…, select a .mcpb file and follow the prompts.
This repository currently publishes an npm stdio package and does not contain a .mcpb bundle. For Claude Desktop builds that still support local configuration, use the following JSON stdio configuration as a fallback:
{
"mcpServers": {
"google-custom-search": {
"command": "npx",
"args": ["-y", "mcp-google-custom-search@latest"],
"env": {
"GOOGLE_CUSTOM_SEARCH_API_KEY": "your_api_key",
"GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "your_engine_id"
}
}
}
}In those builds, save it to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.
Claude Desktop MCP documentation
Add this to ~/.cursor/mcp.json on macOS/Linux or %USERPROFILE%\.cursor\mcp.json on Windows:
{
"mcpServers": {
"google-custom-search": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-google-custom-search@latest"],
"env": {
"GOOGLE_CUSTOM_SEARCH_API_KEY": "your_api_key",
"GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "your_engine_id"
}
}
}
}Run MCP: Open User Configuration and add:
{
"servers": {
"google-custom-search": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-google-custom-search@latest"],
"env": {
"GOOGLE_CUSTOM_SEARCH_API_KEY": "${input:custom_search_api_key}",
"GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "${input:custom_search_engine_id}"
}
}
},
"inputs": [
{ "type": "promptString", "id": "custom_search_api_key", "description": "Google Cloud API key", "password": true },
{ "type": "promptString", "id": "custom_search_engine_id", "description": "Programmable Search Engine id (cx)" }
]
}Check it with MCP: List Servers.
What you can ask it to do
Search the web
Find recent tutorials on a topic and summarize the top results.
Search only within
docs.python.org— or everywhere except a site you distrust.Show the next page of results for the same query.
Narrow the results
Only English pages published in the last month.
Only PDF files; require an exact phrase or exclude a term.
Restrict to one country's content, or to material with specific usage rights.
Find images
Find large photos on a topic, with dimensions and thumbnails.
Only clipart or line drawings, black and white ones.
Show the page each image comes from.
Go beyond the typed tools
Call the API with parameters the typed tools don't expose —
fieldsto trim the response,lowRange/highRange,hq.Fetch the raw response envelope with promotions and the full
pagemap.
How a search works
Every query runs through a Programmable Search Engine, identified by its
cxid — the configured default or a per-callengine_id. The engine's configuration decides coverage: a list of specific sites, or the entire web when "Search the entire web" is enabled.Results come back normalized — title, URL, snippet and metadata — with
next_start/previous_startcursors for paging.total_resultsis Google's estimate and can shrink while paging.The API returns at most 10 results per call and 100 per query (
start + num - 1must stay ≤ 100). The server rejects a wider window before the request — the API would answer400after burning a quota unit.Image search requires Image search enabled in the engine's control panel; otherwise the API answers
400.
A corrected_query in the response is a spelling suggestion only — the results are still for the original query. And this is Programmable Search, not Google Search Console: the API cannot report how your own site is indexed or ranked.
What can change
Operation | What happens | Confirmation boundary |
Web search ( | Reads search results from your engine | No change |
Image search ( | Reads image results from your engine | No change |
Raw API request ( | GET against any Custom Search API path | No change — the API has no write endpoint |
Every tool carries the read-only annotation, the escape hatch included. The Custom Search JSON API is a single GET endpoint with no writes, so the only thing a call spends is a unit of your daily quota.
Getting access
Google Custom Search authenticates with an API key; no OAuth and no scopes are involved.
Create or select a Google Cloud project and enable the Custom Search API.
Create an API key under APIs & Services → Credentials. Restricting the key to the Custom Search API is a good habit.
Create a Programmable Search Engine in the control panel and copy its Search engine ID (
cx). Enable Search the entire web for open-web search and Image search for the image tool.
Treat the API key as a password. The server sends it in the X-Goog-Api-Key header, never in a URL, so logged or echoed URLs cannot leak it.
Configuration
Variable | Required | Description |
| Yes | Google Cloud API key with the Custom Search API enabled. Secret. |
| Recommended | Default Programmable Search Engine id ( |
| No | Custom Search API base URL override. |
| No | Per-request timeout; default |
| No | Transient-error retries (429/5xx/network); default |
Without credentials the server still starts and completes the MCP handshake; the first tool call explains exactly which variables to set. The one malformed setup is an engine id without an API key — the key cannot be supplied per call, so both must be set together.
Data, limits and background work
Requests go to Google. The local server calls the Custom Search JSON API. Its anonymous telemetry contains an installation ID, package version, AI client and platform versions, and tool names — never the API key, search queries, results or tool arguments. For each tool call it also sends the outcome and, on failure, an excerpt of the error text with e-mails, addresses, tokens, numbers of 4+ digits and quoted text replaced by
#; a value from your request can appear in it if the error text contains it. SetASKADS_TELEMETRY=0to opt out.Google applies a daily quota. Every call from any of the three tools costs one unit of the per-project quota — 100 queries per day free, up to 10,000 per day with billing. On
429, the server backs off honoringRetry-After; because the whole API is idempotent GETs,5xxand network errors are retried too, while400/403fail fast.There is no background polling. The server runs only when called. If your AI app supports scheduled tasks, it can rerun a search periodically — each run still spends quota units.
Technical documentation
MCP capability catalog — task-oriented pages for every tool.
Support
Found a bug or need a scenario? Create an issue or write in Telegram.
Available Tools
3 toolsraw_requestRaw Custom Search API callARead-onlyIdempotent
Escape hatch: performs a GET against any Custom Search JSON API path and returns the raw, unnormalized response envelope (queries.request/nextPage, searchInformation, promotions, context, items[] with htmlSnippet/htmlTitle/formattedUrl and the full pagemap). Use it for parameters the typed tools don't expose (lowRange/highRange, c2coff, hq, fields) — e.g. path "customsearch/v1?q=test&num=3&fields=items(title,link)". The API key is added automatically (in a header, never the URL) and the configured engine id is filled in when the path has no cx parameter. The API has GET endpoints only, so nothing here can modify data.
Inputs: path (required).
searchWeb searchARead-onlyIdempotent
Web search through your Google Programmable Search Engine (Custom Search JSON API). Returns query, total_results (Google's estimate — it can shrink while paging), search_time_seconds, corrected_query (spelling suggestion; results are still for the original query), next_start/previous_start page cursors, and items[] with title, url, display_link, snippet, mime/file_format and (with include_pagemap) pagemap metadata. Coverage is the engine's configuration: an engine listing specific sites searches only those; open-web search needs "Search the entire web" enabled in its control panel — results still differ from google.com. Max 10 results per call and 100 per query: paginate by passing next_start as start. Each call costs one unit of the daily quota (free tier 100/day), so prefer one precise query over many broad ones. Note: this is Programmable Search, NOT Google Search Console — it cannot report how your own site is indexed or ranked.
Inputs: query (required), num, safe, sort, +16 more.
search_imagesImage searchARead-onlyIdempotent
Image search through your Google Programmable Search Engine (searchType=image). Works only when the engine has "Image search" enabled in its control panel — otherwise the API answers 400. Each item's url is the image file itself; image.context_url is the page hosting it, with width/height/byte_size and a thumbnail_url (plus its dimensions) for previews. Everything else matches the search tool: same filters (language/country, safe search, site include/exclude, date_restrict, file_type, rights — use rights for reusable images), same pagination (max 10 per call, 100 per query, paginate via next_start), same quota (one unit per call). Image-only filters: size (icon..huge), type (clipart/face/lineart/stock/photo/animated), color_type (mono/gray/color/trans) and dominant_color.
Inputs: query (required), num, safe, size, +20 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
search and search_images are clearly separated by result type, and raw_request is explicitly an escape hatch for raw API access. There is no plausible confusion between these three tools.
search and search_images follow a clear verb_noun pattern with consistent lowercase snake_case. raw_request breaks that pattern slightly, but it is a conventional escape-hatch name and not confusing.
Three tools are well-scoped for the Google Custom Search JSON API: web search, image search, and a raw request fallback. Each tool earns its place without redundancy or unnecessary bloat.
The tool set fully covers the API's read-only capabilities: standard web search, image search, pagination, filters, and every remaining parameter via raw_request. There are no meaningful gaps, and no CRUD is needed since the API only supports GET.
Maintenance
Related MCP Connectors
Search Google straight from your AI agent. Web results, images, videos, news, products, scholarly ar
Provides AI assistants with access to Seltz's powerful Web Search capabilities.
Google Web Search: Google Web Search API. Search the world’s information, including webpages.
Google search, news, maps, webpages, cited answers, research and ChatGPT/Gemini answers for agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables web searching and content scraping through Google Custom Search API. Provides tools to search the internet, extract webpage content, and automatically scrape search results for comprehensive information gathering.3MIT
- AlicenseAqualityDmaintenanceEnables users to perform Google Custom Search queries through the Model Context Protocol. Requires Google API credentials and Custom Search Engine configuration for web search functionality.1MIT
- FlicenseNot gradedqualityDmaintenanceEnables web search capabilities through a remote smart search API with configurable result count, pagination, language, and safety filters, returning structured JSON results.-
- AlicenseBqualityDmaintenanceEnables performing Google searches using the Custom Search Engine API with support for various parameters like date restriction, site search, and file type. Returns search results in a conversational format.1Apache 2.0