ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Find and Use a Google Search MCP Server on GitHub

Find a Google Search MCP server on GitHub, configure Google Custom Search credentials, connect Claude or another MCP client, and troubleshoot setup.

By the ScreenshotNeo team1 October 20269 min read

Short answer: start by choosing a community Google Search MCP server whose runtime and transport match your client. The reviewed GitHub implementations use Google Custom Search credentials: a Google API key and a Programmable Search Engine ID. Python options commonly run over stdio, while one Python project also documents SSE/HTTP and Docker. A Node.js option requires Node.js 18 or newer. A hosted option uses a provider API key and streamable HTTP instead of running the server yourself.

An MCP server exposes search as a callable tool. It is not a replacement for Claude, Cursor, or another MCP client; the client launches or connects to the server and then invokes its search tools.

1. Choose the right implementation

Option Runtime Credentials Transport and deployment When it fits
gradusnikov/google-search-mcp-server Python GOOGLE_API_KEY and GOOGLE_CSE_ID Local process; README uses FastMCP and stdio-style mcp run Small local setup with a short Python workflow
hunter-arton/google_search_mcp_server Node.js 18+ Google Custom Search API key and Search Engine ID Build with npm, then launch the built server from an MCP client Node teams or clients already using JavaScript tooling
artryazanov/google-search-mcp Python Environment variables or command-line credentials Documents stdio, SSE/HTTP, and Docker Local, containerized, or remotely reachable deployments
HasData hosted Google Search/SERP MCP Hosted service Provider API key in an x-api-key header Streamable HTTP; local stdio launchers are documented for clients that cannot connect remotely When you want the provider to operate the server

These are community or vendor implementations, not one canonical Google-managed general web-search server. Before installing one, inspect its current commits, issues, releases, license, dependencies, and client instructions. The reviewed material does not establish which repository is best maintained or most reliable.

2. Prepare Google Custom Search credentials

  1. Create or select a Google Cloud project and enable the Custom Search JSON API according to Google’s current console instructions.
  2. Create an API key with the narrowest practical restrictions.
  3. Create a Programmable Search Engine and copy its Search Engine ID (often called the CSE ID).
  4. Keep the API key and Search Engine ID separate. Both values are required by the self-hosted examples.

Do not commit either value to Git. Use a local .env file, your operating system’s secret store, or your deployment platform’s secret settings.

3. Python setup with gradusnikov/google-search-mcp-server

The repository README documents this flow: clone the repository, install fastmcp, google-api-python-client, and python-dotenv, create a .env file, then run the server with mcp run google_search_mcp_server.py. Follow the repository’s current README for the exact clone URL and any changes to filenames.

git clone <repository-url-from-the-current-readme>
cd google-search-mcp-server
python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows PowerShell: .venv\\Scripts\\Activate.ps1
python -m pip install --upgrade pip
pip install fastmcp google-api-python-client python-dotenv

Create .env in the project directory:

GOOGLE_API_KEY=replace_with_your_google_api_key
GOOGLE_CSE_ID=replace_with_your_search_engine_id

Start it:

mcp run google_search_mcp_server.py

Keep this process available while your MCP client uses it. If the repository’s current instructions use a different entry point, use that entry point instead of guessing.

Claude Desktop-style local configuration

The README also shows a Claude Desktop installation through Smithery. Client configuration formats change, so copy the current snippet from the repository or your client’s current MCP documentation. A generic local-process shape looks like this:

{
  "mcpServers": {
    "google-search": {
      "command": "mcp",
      "args": ["run", "/absolute/path/google_search_mcp_server.py"],
      "env": {
        "GOOGLE_API_KEY": "your-key",
        "GOOGLE_CSE_ID": "your-search-engine-id"
      }
    }
  }
}

Use an absolute path, restart the client after editing its configuration, and check the client’s MCP logs for startup errors.

4. Node.js setup with hunter-arton/google_search_mcp_server

This repository documents Node.js 18 or newer, npm, a Google Cloud account, a Google Custom Search API key, a Search Engine ID, and an MCP-compatible client.

node --version   # must be v18 or newer
npm --version
git clone <repository-url-from-the-current-readme>
cd google_search_mcp_server
npm install

Set the environment variables named by the repository’s current README. A typical pattern is:

GOOGLE_API_KEY=replace_with_your_google_api_key
GOOGLE_CSE_ID=replace_with_your_search_engine_id

Build the server:

npm run build

Then configure your MCP client to launch the generated JavaScript entry point. Use the actual output path from the repository:

{
  "mcpServers": {
    "google-search": {
      "command": "node",
      "args": ["/absolute/path/google_search_mcp_server/dist/index.js"],
      "env": {
        "GOOGLE_API_KEY": "your-key",
        "GOOGLE_CSE_ID": "your-search-engine-id"
      }
    }
  }
}

If npm run build creates a different file, use that file. Do not copy a placeholder repository URL or assume the compiled entry point without checking the current README.

5. Python setup with multiple transports and Docker

artryazanov/google-search-mcp documents stdio mode, SSE/HTTP mode, command-line or environment-variable credentials, and Docker examples. This makes it useful when your client can connect to a remote process or when you want a reproducible container.

For local development, install the dependencies listed by the repository and pass the Google API key and Search Engine ID using the documented environment variables. For Docker, use the repository’s Dockerfile and pass secrets at runtime:

docker build -t google-search-mcp .
docker run --rm -i \
  -e GOOGLE_API_KEY="$GOOGLE_API_KEY" \
  -e GOOGLE_CSE_ID="$GOOGLE_CSE_ID" \
  google-search-mcp

For SSE or HTTP, bind only to an interface and port appropriate for your network, add authentication at the boundary, and follow the repository’s current command-line flags. Stdio is usually simpler and keeps the server local; HTTP is useful when several clients or machines need access.

6. Hosted Google Search MCP

HasData documents a hosted Google Search/SERP MCP service using streamable HTTP and an x-api-key header. Its README also provides local stdio launchers for clients that cannot connect directly to a remote endpoint. This changes the trust model: your searches and provider credential are handled through an external service, while deployment and updates are handled for you.

{
  "mcpServers": {
    "google-search": {
      "url": "<endpoint-from-the-provider's-current-documentation>",
      "headers": {
        "x-api-key": "your-provider-api-key"
      }
    }
  }
}

HasData’s repository currently claims 1,000 free credits per month and describes that as 100 full-SERP calls or 200 calls costing five credits. Treat those numbers as the provider’s own offer; verify current pricing, limits, retention, and terms before relying on them.

7. Test the server from your MCP client

  1. Restart the client after changing its MCP configuration.
  2. Ask the client to list available tools. Confirm that a Google search tool appears.
  3. Run a narrow query such as “site:developers.google.com MCP”.
  4. Check that the response includes titles, URLs, and snippets, and that the result count is plausible.
  5. Try an image-search tool only with a repository that documents one, such as the reviewed Node implementation.

The exact tool name and argument schema are repository-specific. Let the client inspect the tool schema instead of hard-coding a guessed name.

8. cURL, Python, and Node.js checks

An MCP server normally speaks stdio or MCP HTTP rather than exposing Google’s JSON endpoint directly. These checks validate your credentials independently, which helps separate Google API problems from MCP configuration problems. Use the current Google Custom Search REST endpoint and parameters from Google’s documentation.

curl -G "https://www.googleapis.com/customsearch/v1" \
  --data-urlencode "key=$GOOGLE_API_KEY" \
  --data-urlencode "cx=$GOOGLE_CSE_ID" \
  --data-urlencode "q=MCP server"
import os
import requests

params = {
    "key": os.environ["GOOGLE_API_KEY"],
    "cx": os.environ["GOOGLE_CSE_ID"],
    "q": "MCP server",
}
r = requests.get("https://www.googleapis.com/customsearch/v1", params=params, timeout=30)
r.raise_for_status()
print(r.json())
const params = new URLSearchParams({
  key: process.env.GOOGLE_API_KEY,
  cx: process.env.GOOGLE_CSE_ID,
  q: 'MCP server'
});
const res = await fetch(`https://www.googleapis.com/customsearch/v1?${params}`);
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

These snippets are diagnostic calls, not replacements for the MCP server. Never expose the key in browser-side code.

9. Troubleshooting

Symptom Likely cause Fix
Client says the server exited immediately Wrong command, script path, working directory, or runtime Run the command in a terminal first; use absolute paths and verify Python or Node versions.
401/403 from Google Invalid key, disabled API, restrictive key policy, or wrong project Enable the Custom Search JSON API, verify the key’s project and restrictions, and retry the direct REST check.
No results or “invalid value” for cx Search Engine ID is missing or copied incorrectly Copy the Search Engine ID from the Programmable Search Engine control panel.
Environment variables appear empty .env is in the wrong directory or the client does not load it Use the repository’s documented environment mechanism or put variables directly in the client configuration.
Tool is missing in the client Server failed during initialization or the client cached an old configuration Inspect MCP logs, restart the client, and verify the server’s startup output.
Node build fails Node is older than 18, dependencies are stale, or TypeScript compilation fails Use Node 18+, remove and reinstall dependencies, then follow the repository’s current build instructions.
Remote HTTP connection fails Wrong transport, endpoint, header, firewall, or TLS configuration Confirm the provider’s current streamable HTTP settings and test the endpoint from the same machine as the client.
Quota errors after a few searches Google or hosted-provider quota has been reached Review the relevant console, reduce repeated queries, add caching where appropriate, or change the plan.

10. Security, reliability, and cost considerations

  • Secrets: keep Google keys and provider keys out of source control and logs. Restrict keys to the required API and projects.
  • Repository risk: review code, dependencies, license, issue activity, and release history before running third-party servers with access to your client environment.
  • Transport: stdio avoids exposing a network port. If you use HTTP or SSE, add authentication, TLS, network restrictions, and request logging that does not record secrets.
  • Reliability: a local server depends on your machine, runtime, network, Google API availability, and repository compatibility. A hosted server removes local process management but adds provider availability and policy dependencies.
  • Latency: search time includes MCP transport, server startup (if launched per request), Google’s response, and result processing. Keep a persistent process when your client supports it.
  • Cost: Google API quotas and any hosted-provider billing are separate from your MCP client. Verify current quotas and prices in the relevant console. HasData’s free-credit statement is provider-specific and can change.

11. Or skip the browser setup

If your goal is to give an agent clean screenshots of search results or documentation pages, ScreenshotNeo provides a website screenshot API and MCP server. The API accepts one GET request and returns PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for all options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' }); const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers identify the page verdict and whether it was billed. Its MCP server includes take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000 screenshots.

Sign up for ScreenshotNeo free with 1,000 screenshots a month and no card.

12. FAQ

Is there an official Google general web-search MCP server on GitHub?

The reviewed official Google pages document managed MCP services for supported Google and Google Cloud products, plus a Developer Knowledge MCP server for Google developer documentation. They do not document a Google-managed general web-search MCP server in the reviewed material.

Do I need both a Google API key and a Search Engine ID?

Yes for the reviewed self-hosted Google Custom Search implementations. A hosted provider uses its own credential model instead.

Which repository should I choose?

Choose based on Python versus Node.js, stdio versus HTTP, Docker needs, and how much operation you want to own. The research does not establish a universally best or most reliable repository.

Can an MCP server search the whole web automatically?

It can invoke the search backend and return the backend’s results, subject to Google’s configuration, quotas, and policies. The MCP protocol itself does not expand search coverage.

Can I connect a remote server from every MCP client?

No. Client support for streamable HTTP, SSE, authentication headers, and remote URLs varies. Use a documented local launcher when the client cannot connect remotely.

Keep reading