Google Search

This repository provides a Model Context Protocol (MCP) server that retrieves information from Google Search to provide context to Large Language Models (LLMs). It uses the Google Custom Search JSON API to fetch real-time web search results, allowing AI assistants to ground their responses in up-to-date information.

Overview

The Google Search MCP server acts as a bridge between LLMs and Google's search engine. Through a standardized MCP interface, an LLM can issue search queries and receive relevant results. This enables AI assistants to fetch current information from the web beyond their training data.

Features

• Search the Web: Perform Google searches and retrieve top web results (titles, snippets, URLs) for a query.
• Real-Time Information: Access the latest information available online via live Google searches.
• Configurable Results Limit: Specify the number of results to return for a query (default 10, up to 50).
• Optional Caching: Enable caching of query results to improve performance on repeated queries.
• STDIO and SSE Support: Run the server in stdio mode for direct integration (as a subprocess) or in sse mode to serve queries over HTTP (using Server-Sent Events).

Requirements

• Python 3.8+ – The server is written in Python and requires version 3.8 or higher.
• Google API Credentials – A Google Custom Search API Key and Search Engine ID (CX) are needed (see Getting API Credentials).
• Internet Access – The server must have network access to call the Google Custom Search API.

Getting API Credentials

To use this server, you need to obtain the following from Google:

1. Google API Key: Create a project in the Google Cloud Console and enable the Custom Search API. Then generate an API key in the Google Cloud Console.
2. Custom Search Engine ID (CX): Create a search engine in the Google Custom Search Engine (CSE) control panel. Configure it to search the entire web (or specific sites, as needed). Once created, note the search engine ID (an alphanumeric string labeled "cx").

Note: Both the API key and the search engine ID are required for the server to function. Keep these credentials secure and do not commit them to source control or expose them publicly.

Installation

Clone this repository and install the package and dependencies:

git clone https://github.com/artryazanov/google-search-mcp.git
cd google-search-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

This will install the necessary Python packages as listed in requirements.txt. You can also install the package in editable mode (e.g., pip install -e .) if you plan to modify the code.

Usage

After installation, you can run the MCP server using the provided console script google-search-mcp or by executing the module. Before running, ensure your Google API credentials are provided either as command-line arguments or via environment variables.

Running the Server (STDIO Mode)

By default, the server runs in stdio mode. In this mode, the server reads requests from standard input and writes responses to standard output. This is suitable for integrating with applications like Claude Desktop or any MCP-compatible client that manages the server process.

Example (running in stdio mode with API credentials):

# Option 1: Provide API credentials via command-line arguments
google-search-mcp --api-key YOUR_GOOGLE_API_KEY --search-engine-id YOUR_CSE_ID

# Option 2: Set credentials as environment variables, then run without arguments
export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
export GOOGLE_SEARCH_ENGINE_ID="YOUR_CSE_ID"
google-search-mcp

When running in stdio mode, the server will start and wait for incoming search requests via stdin (typically from an AI client). Each request (formatted according to MCP) will be processed, and results are returned to stdout as JSON.

Running the Server (SSE/HTTP Mode)

To run the server as an HTTP service, use the --transport sse option. In SSE mode, the server will start an HTTP server and provide a streaming endpoint for search queries.

Example (running in SSE mode on port 8080):

google-search-mcp --transport sse --host 0.0.0.0 --port 8080 \
           --api-key YOUR_GOOGLE_API_KEY --search-engine-id YOUR_CSE_ID

This starts the server in SSE mode, listening on all interfaces (0.0.0.0) at port 8080. In this mode, you can send HTTP GET requests to the server's resource endpoints to execute searches. For example, you can open the following URL in a browser or HTTP client to test a query:

http://localhost:8080/search/your%20query%20here

This will return a JSON response containing the search results for "your query here". The SSE transport is primarily useful for network-based deployments or streaming results in real-time to clients over HTTP.

Note: When running in Docker or Kubernetes, use --host 0.0.0.0 to bind to all interfaces, and ensure the container's port is published (e.g., -p 8080:8080).

Command-Line Options

• --api-key, -k (string): Your Google API key for the Custom Search API. If not provided, the server will look for the GOOGLE_API_KEY environment variable.
• --search-engine-id, -e (string): Your Google Custom Search Engine ID (CX). If not provided, the server will use the GOOGLE_SEARCH_ENGINE_ID environment variable.
• --transport, -t (string): Transport protocol for the server. Either stdio (default) or sse (to run an HTTP server with Server-Sent Events).
• --host (string): Host address to bind the HTTP server in SSE mode (default: 127.0.0.1).
• --port (int): Port number for SSE mode (default: 8080).
• --enable-cache (flag): Enable in-memory caching of search results. If this flag is set, the server will cache results for identical queries during its runtime.

Run google-search-mcp --help to see this usage information.

Available MCP Tool

This server provides one MCP tool that the LLM can use:

search_google

Description: Searches Google for a given query and returns the top results.

Parameters:

• query (string, required) – The search query term.
• limit (integer, optional) – The maximum number of results to return (default is 10).

Returns: A JSON object with the following structure:

• query: The query string that was searched.
• results: A list of result objects. Each result has:
  • title: The title of the result page.
  • link: The URL of the result page.
  • snippet: A brief snippet of text from the page (as provided by Google).
• error: optional – An error message string, if an error occurred during the search (this field is only present if there was an error; on success it is omitted).

The search_google tool is registered with the MCP server, so an LLM client can call this function to perform a web search. In stdio mode, the function is invoked via the MCP protocol messages. In sse (HTTP) mode, the server exposes a GET endpoint /search/{query} that returns the same data.

Testing

This project includes a test suite to ensure the server works correctly.

1. Install test dependencies: pip install -r requirements-dev.txt (includes pytest).
2. Run all tests: pytest

The tests are organized in the tests/ directory:

• Unit tests (in test_basic.py, test_cli.py, etc.) use mocked responses to test functionality without calling the real Google API.
• Integration tests (marked with @pytest.mark.integration) will actually call the Google API. These are skipped by default unless you set valid GOOGLE_API_KEY and GOOGLE_SEARCH_ENGINE_ID environment variables before running pytest.

Docker

You can build and run this server using Docker for convenience and deployment:

# Build the Docker image
docker build -t google-search-mcp .

# Run the server in SSE mode on port 8080
docker run --rm -p 8080:8080 \
  -e GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" \
  -e GOOGLE_SEARCH_ENGINE_ID="YOUR_CSE_ID" \
  google-search-mcp --transport sse --host 0.0.0.0 --port 8080

This will start the containerized server accessible at http://localhost:8080. The environment variables for the API key and search engine ID are passed into the container to authenticate with Google.

Using the MCP Server with Junie (JetBrains) via Docker

Junie (the AI coding agent in JetBrains IDEs) supports external MCP servers via stdio transport. This means Junie can launch your MCP server as a subprocess and communicate with it through stdin/stdout. If you package the Google Search MCP server into a Docker image, Junie can start it automatically.

1. Build the Docker Image

From the project root (where the Dockerfile is located):

docker build -t google-search-mcp:local .

This creates a local Docker image named google-search-mcp:local.

2. Configure Junie

Open Settings > Tools > Junie > MCP Settings and add a new server. Junie stores these settings in ~/.junie/mcp/mcp.json (Linux/macOS) or %USERPROFILE%\.junie\mcp\mcp.json (Windows).

Add an entry like this:

{
  "mcpServers": {
    "google-search-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GOOGLE_API_KEY=your-api-key",
        "-e", "GOOGLE_SEARCH_ENGINE_ID=your-cse-id",
        "google-search-mcp:local"
      ]
    }
  }
}

Note for Windows: If Docker is not found on PATH, specify the full path to docker.exe in the "command" field, for example:

{
  "mcpServers": {
    "google-search-docker": {
      "command": "C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe"
    }
  }
}

Explanation:

• command: "docker" – Junie will use Docker CLI to launch the server.
• --rm -i – ensures the container is removed after exit and stays interactive for stdio.
• -e – passes Google API credentials into the container.
• google-mcp:local – the tag of your local image.

License

This project is licensed under the Unlicense license. See the LICENSE file for details.