A1-x-Tech/mcp-google-custom-search

**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).
1. Get an API key and an engine id.
2. Add the server to your AI app.
3. Ask the read-only question above.
Codex
**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 documentation
Claude Code
Claude Code MCP documentation
Claude Desktop
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:
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
Cursor
Add this to ~/.cursor/mcp.json on macOS/Linux or %USERPROFILE%\.cursor\mcp.json on Windows:
Cursor MCP documentation
VS Code
Run **MCP: Open User Configuration** and add:
Check it with **MCP: List Servers**.
VS Code MCP documentation