mcp-google-custom-search
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| ASKADS_TELEMETRY | No | Set to 0 to opt out of anonymous telemetry. | |
| GOOGLE_CUSTOM_SEARCH_API_KEY | Yes | Google Cloud API key with the Custom Search API enabled. Secret. | |
| GOOGLE_CUSTOM_SEARCH_API_BASE | No | Custom Search API base URL override. | |
| GOOGLE_CUSTOM_SEARCH_ENGINE_ID | No | Default Programmable Search Engine id (cx); tools accept a per-call engine_id override. | |
| GOOGLE_CUSTOM_SEARCH_TIMEOUT_MS | No | Per-request timeout; default 30000 ms. | |
| GOOGLE_CUSTOM_SEARCH_MAX_RETRIES | No | Transient-error retries (429/5xx/network); default 3. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| searchA | 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. |
| search_imagesA | 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. |
| raw_requestA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.