This server provides three read-only MCP tools for searching the web and images through your Google Programmable Search Engine.
Web search (search) — run Google-syntax queries with pagination via next_start, and narrow by language, country, date, site include/exclude, file type, exact/excluded/OR terms, usage rights, safe search, duplicate filtering, and optional page metadata.
Image search (search_images) — find images with file URL, dimensions, byte size, thumbnail, and host page; filter by image size, type, color type, dominant color, plus the same general filters and pagination.
Raw API call (raw_request) — GET any Custom Search API path as an escape hatch for parameters the typed tools don't expose (e.g. fields, lowRange/highRange, hq), with the API key injected automatically.
All tools are read-only and idempotent, respect quota limits (max 10 results/call, 100/query), and search coverage depends on the configured engine.
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 "Install 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.
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-Key header 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
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: Web Search MCP Server
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.
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.
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 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.
Call the API with parameters the typed tools don't expose — fields to trim the response, lowRange/highRange, hq.
Fetch the raw response envelope with promotions and the full pagemap.
Every query runs through a Programmable Search Engine, identified by its cx id — the configured default or a per-call engine_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_start cursors for paging. total_results is Google's estimate and can shrink while paging.
The API returns at most 10 results per call and 100 per query (start + num - 1 must stay ≤ 100). The server rejects a wider window before the request — the API would answer 400 after 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.
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.
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.
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.
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. Set ASKADS_TELEMETRY=0 to 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 honoring Retry-After; because the whole API is idempotent GETs, 5xx and network errors are retried too, while 400/403 fail 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.
MCP capability catalog — task-oriented pages for every tool.
Found a bug or need a scenario? Create an issue or write in Telegram.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | API path with query string, relative to https://customsearch.googleapis.com — e.g. "customsearch/v1?q=hello&num=3". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description reinforces these by stating 'The API has GET endpoints only, so nothing here can modify data.' It also discloses auth behavior (key added in a header, engine id auto-filled), which is valuable beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but information-dense, front-loading the purpose ('Escape hatch') and then efficiently covering usage, examples, auth behavior, and safety. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter escape-hatch tool, the description is complete: it specifies the path format, the base URL, the response shape, the parameter coverage gap it fills, and the safety guarantees. No output schema exists, so the description appropriately carries the burden of explaining the return envelope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already documents the path parameter. The description adds meaningful context with the relative-to-base URL clarification, an example path, and side behaviors like automatic key/engine-id injection, which goes beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb and resource: 'performs a GET against any Custom Search JSON API path and returns the raw, unnormalized response envelope.' It also distinguishes itself from typed sibling tools by explicitly targeting parameters the typed tools do not expose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit when-to-use condition: 'Use it for parameters the typed tools don't expose (lowRange/highRange, c2coff, hq, fields).' It also provides a concrete example path and explains how the API key and engine id are handled, making the invocation context unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| num | No | Results per page, 1..10 (API maximum 10; default 10). | |
| safe | No | Safe search: active filters adult content, off (the API default) does not. | |
| sort | No | Sort expression, e.g. "date" for newest-first. Omit for relevance (usually better). | |
| query | Yes | The search query, Google syntax included (quotes, site:, filetype:, OR, -exclusions). | |
| start | No | 1-based index of the first result — use next_start/previous_start from the previous page. The API serves at most 100 results per query, so start + num - 1 must stay <= 100 (enforced: a wider window is rejected without spending quota). | |
| rights | No | License filter: cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived (combine with |). | |
| country | No | Geolocation bias — rank results as if searching from this country, e.g. "de". Soft signal. | |
| language | No | Only results in this language, e.g. "en", "de", "zh-CN". | |
| or_terms | No | Space-separated words — each result must contain at least one of them. | |
| engine_id | No | Programmable Search Engine id (cx) to search with, overriding the configured GOOGLE_CUSTOM_SEARCH_ENGINE_ID. Omit to use the configured engine. | |
| file_type | No | Only files of this type, e.g. "pdf", "xlsx", "svg". | |
| exact_terms | No | A phrase every result must contain. | |
| site_search | No | A site or domain to include or exclude, e.g. "example.com" — pair with site_search_filter. | |
| date_restrict | No | Only results from the last N days/weeks/months/years: "d7", "w2", "m6", "y1", ... | |
| exclude_terms | No | A word or phrase no result may contain. | |
| include_pagemap | No | Attach each result's raw pagemap (OpenGraph/metatags/thumbnails and other structured page data). Verbose — leave off unless you need page metadata. | |
| country_restrict | No | Hard filter — only documents Google attributes to this country, e.g. "DE". | |
| filter_duplicates | No | Google's duplicate-content filter (default on). false returns near-duplicate results too. | |
| interface_language | No | Interface language used to interpret the query, e.g. "de". Improves non-English relevance. | |
| site_search_filter | No | include = only results from site_search, exclude = everything but it. Default include. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish read-only, open-world, idempotent, non-destructive behavior, and the description adds valuable context on top: Google's total_results can shrink while paging, corrected_query does not change the actual results, each call consumes one unit of a daily quota, and engine coverage depends on the control-panel configuration. These details go well beyond the structured hints and help an agent predict real behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence carries distinct information: return fields, pagination, quota, coverage caveats, and the Search Console distinction. It is front-loaded with the core purpose and follows with operational constraints. No sentence is filler or redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by enumerating the returned fields and their caveats. For a 20-parameter tool with one required parameter, it covers what results look like, how pagination works, quota implications, and engine coverage. An agent has enough context to invoke it correctly without guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, and the description still adds meaning beyond the schema: it explains the next_start pagination mechanism, the 10-per-call/100-per-query limits, and the cost of each call against the quota. This is useful semantic context for choosing parameter values, though the schema itself already documents each parameter well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Web search through your Google Programmable Search Engine (Custom Search JSON API).' It clearly conveys this is a web search tool returning query metadata and result items, which distinguishes it from the sibling image search and from Google Search Console. The explicit 'NOT Google Search Console' note further sharpens the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear operational guidance: paginate with next_start, stay within the 100-result window, and prefer one precise query because each call consumes quota. It explicitly says the tool cannot report how your own site is indexed or ranked, a useful when-not-to-use exclusion. It does not explicitly route to search_images or raw_request, so it stops short of naming alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| num | No | Results per page, 1..10 (API maximum 10; default 10). | |
| safe | No | Safe search: active filters adult content, off (the API default) does not. | |
| size | No | Image size class, from icon to huge. | |
| sort | No | Sort expression, e.g. "date" for newest-first. Omit for relevance (usually better). | |
| type | No | Kind of image. | |
| query | Yes | The search query, Google syntax included (quotes, site:, filetype:, OR, -exclusions). | |
| start | No | 1-based index of the first result — use next_start/previous_start from the previous page. The API serves at most 100 results per query, so start + num - 1 must stay <= 100 (enforced: a wider window is rejected without spending quota). | |
| rights | No | License filter: cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived (combine with |). | |
| country | No | Geolocation bias — rank results as if searching from this country, e.g. "de". Soft signal. | |
| language | No | Only results in this language, e.g. "en", "de", "zh-CN". | |
| or_terms | No | Space-separated words — each result must contain at least one of them. | |
| engine_id | No | Programmable Search Engine id (cx) to search with, overriding the configured GOOGLE_CUSTOM_SEARCH_ENGINE_ID. Omit to use the configured engine. | |
| file_type | No | Only files of this type, e.g. "pdf", "xlsx", "svg". | |
| color_type | No | mono = black & white, trans = transparent background. | |
| exact_terms | No | A phrase every result must contain. | |
| site_search | No | A site or domain to include or exclude, e.g. "example.com" — pair with site_search_filter. | |
| date_restrict | No | Only results from the last N days/weeks/months/years: "d7", "w2", "m6", "y1", ... | |
| exclude_terms | No | A word or phrase no result may contain. | |
| dominant_color | No | Prefer images dominated by this color. | |
| include_pagemap | No | Attach each result's raw pagemap (OpenGraph/metatags/thumbnails and other structured page data). Verbose — leave off unless you need page metadata. | |
| country_restrict | No | Hard filter — only documents Google attributes to this country, e.g. "DE". | |
| filter_duplicates | No | Google's duplicate-content filter (default on). false returns near-duplicate results too. | |
| interface_language | No | Interface language used to interpret the query, e.g. "de". Improves non-English relevance. | |
| site_search_filter | No | include = only results from site_search, exclude = everything but it. Default include. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description reveals important behavior: the 400 error condition, the meaning of item.url vs image.context_url, thumbnail and size fields, quota cost, pagination behavior via next_start, and the full set of image-only filters. This is rich, non-obvious behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place. It front-loads the core purpose and the critical engine prerequisite, then covers result shape, shared behavior, and image-only filters in a logical progression. It efficiently leverages the sibling search tool instead of repeating all shared details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 24 parameters, no output schema, and meaningful API quirks, the description is remarkably complete. It covers prerequisites, error conditions, result semantics, pagination, quotas, shared filters, and image-specific filters, leaving little ambiguity for an agent needing to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters well. The description still adds value by grouping filters, clarifying shared semantics with the search tool, emphasizing 'use rights for reusable images', and explaining pagination/quota behavior that the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific operation: image search through a Google Programmable Search Engine with searchType=image. It clearly distinguishes this from the sibling 'search' tool by focusing on image-specific behavior and explicitly saying 'Everything else matches the search tool.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this for image search, and it requires the engine to have Image search enabled, otherwise the API returns 400. It references the alternate generic search tool for shared filters/pagination behavior, though it does not explicitly state 'use search for non-image queries'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0raw_requestsearchsearch_imagessearch 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.
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.
Web search, news, page retrieval, sitemaps, and trending topics through Search1API.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/A1-x-Tech/mcp-google-custom-search'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
