mcp-google-custom-search

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

Contents

• Quick start
• What you can ask it to do
• How a search works
• What can change
• Getting access
• Configuration
• Data, limits and background work
• Technical documentation
• Support

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

• Get an API key and an engine id.
• Add the server to your AI app.
• Ask the read-only question above.

Codex

In the app: open Settings → Plugins → MCP servers, select Add server, then add npx -y mcp-google-custom-search@latest with GOOGLE_CUSTOM_SEARCH_API_KEY and GOOGLE_CUSTOM_SEARCH_ENGINE_ID.

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 Code

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

Claude Desktop

Open Settings → Developer → Edit Config and add:

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

If Edit Config is unavailable, edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.

Claude Desktop MCP documentation

Cursor

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

VS Code

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

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

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.

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

• MCP capability catalog — task-oriented pages for every tool.
• All tools and inputs
• Development documentation
• Publishing documentation
• Custom Search JSON API reference

Support

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

You made it to the end!