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:
- Get a Google API Key from the Google Cloud Console
- 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 stringnum_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.