Overview

This MCP (Model Context Protocol) server wraps the Google Custom Search API and exposes it as a simple, MCP-compatible HTTP tool suitable for use by applications and language models. It provides a small, focused service that forwards search requests to Google Custom Search, applies lightweight result normalization and caching, and returns structured search results that are easy to consume by downstream services or agents.

The server is useful when you need a consistent tool endpoint for search inside an LLM agent, a microservice for site or web search, or a scalable bridge to Google’s search from environments where embedding the Google client libraries is undesirable. It centralizes API key configuration, request parameter mapping, pagination, and basic rate-limiting so clients can treat search as a reliable service.

Features

Exposes Google Custom Search as an MCP-compatible HTTP tool
Simple JSON request/response model suited for LLM tooling and microservices
Supports web and image search via Google Custom Search parameters
Basic caching to reduce duplicate Google API calls and improve latency
Configurable pagination (start, num) and safeSearch/site-restriction options
Docker-friendly and simple local setup with environment variables
Lightweight — designed to be deployed alongside agent runtimes

Installation / Configuration

Prerequisites:

Node.js (16+)
Google Custom Search API key and a Custom Search Engine ID (CX)

Install locally:

git clone https://github.com/adenot/mcp-google-search.git
cd mcp-google-search
npm install
# set env variables (see .env example below) and start
npm start

Docker (build and run):

# Build
docker build -t mcp-google-search .

# Run (example)
docker run -e GOOGLE_API_KEY=your_api_key \
           -e GOOGLE_CX=your_cx \
           -e PORT=3000 \
           -p 3000:3000 \
           mcp-google-search

Example .env (replace with your values):

PORT=3000
GOOGLE_API_KEY=AIza...
GOOGLE_CX=0123456789:abcdefg
CACHE_TTL=300        # seconds, optional
DEFAULT_NUM=5        # results per page
SAFE_SEARCH=moderate # off | moderate | active

Common environment variables:

GOOGLE_API_KEY — required, your Google API key
GOOGLE_CX — required, your Custom Search Engine ID
PORT — optional, HTTP port (default 3000)
CACHE_TTL — optional, seconds to cache identical requests
DEFAULT_NUM — optional, default number of results to return

Available Resources

The server exposes simple HTTP endpoints (default host:port where the server runs). Typical endpoints:

GET /health
- Simple health check that returns 200 when the server is ready.
POST /search
- Main search endpoint for web/image queries.
- Request body (JSON):
  - q (string) — search query (required)
  - num (int) — number of results (optional)
  - start (int) — start index for pagination (optional)
  - site (string) — restrict to a specific site (optional)
  - searchType (string) — “image” for image search (optional)
  - safe (string) — safeSearch setting (optional)
- Response:
  - JSON array of normalized result objects: title, snippet, link, displayLink, cacheId (if any), and optional image metadata

Example request (curl):

curl -X POST http://localhost:3000/search \
  -H "Content-Type: application/json" \
  -d '{"q":"site:example.com privacy policy","num":3}'

Example Node fetch:

const res = await fetch('http://localhost:3000/search', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({ q: 'open source mcp protocol', num: 5 })
});
const results = await res.json();
console.log(results);

Use Cases

LLM Tooling: Expose search as a tool to an LLM agent so it can retrieve current web content, confirm facts, or cite sources during generation. The server presents a stable, JSON-based interface that can be plugged into tool-driven agent flows.
Website Search Integration: Provide a backend search API for a website or dashboard that uses Google’s index and ranking while centralizing API keys and request logic.
Customer Support & KB Augmentation: Use search to fetch relevant documentation pages or support articles to augment responses from an assistant or populate suggested help links.
Automated Monitoring and Research: Batch queries for market or competitive research, leveraging caching and pagination to control API usage and cost.

Notes & Best Practices

Monitor your Google API quotas and set appropriate caching to avoid hitting rate limits.
Restrict your API key and CSE to only the required domains and IPs where possible.
Use safeSearch and site-restriction parameters in production to control returned content.
For LLM integrations, normalize and truncate long snippets before feeding them into model context windows.

GitHub repo: https://github.com/adenot/mcp-google-search — consult the repository for implementation details, sample manifests, and advanced configuration options.

Google Custom Search MCP Server API