A1 AI engineering company GitHub
Connect the Google Custom Search MCP server to your AI agent Open source, MIT, on npm. Setup instructions for Claude, Cursor and Codex are in the repository; adoption questions — Telegram. GitHub repository Telegram

Google Custom Search: Search the web — MCP tool

Google Custom Search MCP tool: Web search through your Programmable Search Engine — structured results with title, URL, snippet and metadata, plus pagination, language/country filters and safe search.

Technical name: search

What task it solves

I want to search the web and get structured, filterable results into my AI session.

Runs one query against the Google Custom Search JSON API through your Programmable Search Engine (cx) and returns a normalized result: the query, Google's total_results estimate, the search time, a spelling suggestion when Google has one, ready-to-use next_start/previous_start page cursors, and items[] with title, url, display_link, snippet, mime/file_format and — on request — the page's pagemap metadata.

When to use it

Use it whenever the session needs live web results: research, fact checking, finding documentation or sources, monitoring what is published about a topic. Coverage is your engine's configuration — an engine listing specific sites searches only those; open-web search needs "Search the entire web" enabled in the engine control panel.

Do not use it to inspect how your own site performs in Google — that is Google Search Console, a different product this API cannot reach.

What to provide

  • query — required. The search query; Google operators (quotes, site:, filetype:, OR, -exclusions) work.
  • Pagination: num (1..10 per page) and start (pass next_start from the previous page; the API serves at most 100 results per query).
  • Filters, all optional: safe (active/off), language (e.g. de), country (ranking bias) vs country_restrict (hard filter), interface_language, site_search + site_search_filter (include/exclude), date_restrict (d7, m6, y1, ...), exact_terms, exclude_terms, or_terms, file_type, rights (license), sort (date), filter_duplicates.
  • include_pagemap — attach each result's raw structured page metadata (verbose).
  • engine_id — a cx override when one server should search through several engines.

What it returns

Compact JSON: query, total_results (an estimate that can shrink while paging), search_time_seconds, corrected_query (suggestion only — the results are still for the original spelling), next_start/previous_start, and items[] as described above. An empty items with a nonzero total_results on far pages means the estimate shrank — go back to earlier pages.

What changes in Google Custom Search

Nothing. The tool reads search results and does not change any data; the Custom Search JSON API has no write endpoint at all. Each call does consume one unit of the per-project daily quota (100 queries/day free, up to 10,000/day billed).

Example request

Search the web for recent PDF reports about battery recycling in Germany — German results from the last year, and give me titles, links and snippets.

Errors and limitations

  • 10 results per call, 100 per query maximum: start + num - 1 must stay ≤ 100 — a wider window is rejected before the request (the API would answer 400 after burning a quota unit).
  • HTTP 429 — daily quota or rate limit exhausted; retrying past the built-in backoff will not help.
  • HTTP 403 — the key: Custom Search API not enabled in the Cloud project, or the key's referrer/IP restrictions block the server.
  • HTTP 400 — usually a bad parameter or a wrong cx.
  • Results and ranking come from the engine configuration and can differ from google.com.

Access also depends on key restrictions, quotas, and upstream API limits.

Related MCP tools

Technical details