google-search-mcp

A Model Context Protocol (MCP) server that utilizes Google Custom Search (CSE) to retrieve information from the internet. By leveraging this MCP, the Large Language Model (LLM) is enabled to perform real-time Web searches.

Prerequisites

A Google Custom Search API key and Custom Search Engine ID are required:

1. Get a Google API Key from the Google Cloud Console
2. Create a Custom Search Engine at Programmable Search Engine

Installation

pip install google-search-mcp

Or install from source:

pip install .

Configuration

Create a .env file in the project root directory:

cp .env.example .env

Then edit the .env file and add your credentials:

GOOGLE_API_KEY=your-api-key
GOOGLE_CSE_ID=your-custom-search-engine-id

Alternatively, you can set environment variables directly:

export GOOGLE_API_KEY="your-api-key"
export GOOGLE_CSE_ID="your-custom-search-engine-id"

Usage

As a CLI

google-search-mcp

With Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

For macOS/Linux:

{
  "mcpServers": {
    "google-search": {
      "command": "python",
      "args": ["-m", "google_search_mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-api-key",
        "GOOGLE_CSE_ID": "your-custom-search-engine-id"
      }
    }
  }
}

For Windows:

If python is in your PATH (check with where python), you can use the same configuration as macOS/Linux:

{
  "mcpServers": {
    "google-search": {
      "command": "python",
      "args": ["-m", "google_search_mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-api-key",
        "GOOGLE_CSE_ID": "your-custom-search-engine-id"
      }
    }
  }
}

If you need to use a specific Python installation, find the full path with:

python -c "import sys; print(sys.executable)"

Then use the full path in the configuration:

{
  "mcpServers": {
    "google-search": {
      "command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Microsoft\\WindowsApps\\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\\python.exe",
      "args": ["-m", "google_search_mcp"],
      "env": {
        "GOOGLE_API_KEY": "your-api-key",
        "GOOGLE_CSE_ID": "your-custom-search-engine-id"
      }
    }
  }
}

Note: Environment variables must be set in the Claude Desktop config env section for the server to access them.

Tools

search

Search the web using Google Custom Search.

Parameters:

• query (string, required): The search query string
• num_results (integer, optional): Number of results to return (1-10, default 10)

Development

Running Tests

Install development dependencies:

pip install -e ".[dev]"

Run the test suite:

pytest

Run tests with verbose output:

pytest -v

Run tests with coverage:

pytest --cov=google_search_mcp --cov-report=html

Test Coverage

The test suite includes comprehensive tests for:

• Successful search requests
• Environment variable validation
• API error handling
• JSON parsing errors
• Empty search results
• Input parameter validation (num_results clamping)
• Result formatting
• Request parameter verification

License

MIT License - see LICENSE for details.