Skip to main content
Glama
mcp-google-custom-search

mcp-google-custom-search

Google Custom Search MCP

English | Русский

npm Glama CI License: MIT

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


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_start cursor 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).

  1. Get an API key and an engine id.

  2. Add the server to your AI app.

  3. 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@latest
codex mcp list

Codex MCP documentation

claude 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@latest
claude mcp list

Claude Code MCP documentation

The 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"
      }
    }
  }
}

Cursor MCP documentation

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.

VS Code MCP documentation

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 — fields to trim the response, lowRange/highRange, hq.

  • Fetch the raw response envelope with promotions and the full pagemap.

How a search works

  1. 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.

  2. 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.

  3. 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.

  4. 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 (search)

Reads search results from your engine

No change

Image search (search_images)

Reads image results from your engine

No change

Raw API request (raw_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.

  1. Create or select a Google Cloud project and enable the Custom Search API.

  2. Create an API key under APIs & Services → Credentials. Restricting the key to the Custom Search API is a good habit.

  3. 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

GOOGLE_CUSTOM_SEARCH_API_KEY

Yes

Google Cloud API key with the Custom Search API enabled. Secret.

GOOGLE_CUSTOM_SEARCH_ENGINE_ID

Recommended

Default Programmable Search Engine id (cx); tools accept a per-call engine_id override.

GOOGLE_CUSTOM_SEARCH_API_BASE

No

Custom Search API base URL 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.

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. 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.

Technical documentation

Support

Found a bug or need a scenario? Create an issue or write in Telegram.

Available Tools

3 tools
raw_requestRaw Custom Search API callA
Read-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).

search_imagesImage searchA
Read-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

    A4.8/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables web search capabilities through a remote smart search API with configurable result count, pagination, language, and safety filters, returning structured JSON results.
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      1
      Apache 2.0