Google Custom Search MCP server for AI agents

The Google Custom Search Engine MCP Server enables large language models to perform Google searches and retrieve results through the Model Context Protocol. This server allows AI models to submit search queries and get back structured search results including titles, links, and snippets, which can be combined with other MCP servers for enhanced capabilities.

Installation Options

Using uv (Recommended)

With uv, no specific installation is needed. You can run the server directly using uvx:

uvx mcp-google-cse

Using PIP

Install via pip:

pip install mcp-google-cse

After installation, run it as a Python module:

python -m mcp-google-cse

Installing via Smithery

For automatic installation with Claude Desktop via Smithery:

npx -y @smithery/cli install @Richard-Weiss/mcp-google-cse --client claude

Configuration

Setting Up Google Custom Search Engine

Before using the server, you need to set up a Google Custom Search Engine:

Go to https://console.cloud.google.com/ and create a new project
Select the project and search for "Custom Search API" in the search bar
Click on the search result and click "Enable"
Go to the Credentials tab and create a new API key
Visit https://programmablesearchengine.google.com to create a new custom search engine
Give your search engine any name
Select "Search the entire web" for a normal Google Search experience
Click "Create" and copy the engine ID
Optionally customize the search engine to your preferences

Note: The free quota allows 100 searches per day.

Configure for Claude App

Add the server to your claude_desktop_config.json using one of these methods:

Using uvx (recommended)

"mcp-google-cse": {
    "command": "uvx",
    "args": ["mcp-google-cse"],
    "env": {
        "API_KEY": "your-api-key",
        "ENGINE_ID": "your-engine-id"
    }
}

Using pip installation

"mcp-google-cse": {
    "command": "python",
    "args": ["-m", "mcp-google-cse"],
    "env": {
        "API_KEY": "your-api-key",
        "ENGINE_ID": "your-engine-id"
    }
}

Running locally

"mcp-google-cse": {
    "command": "uv",
    "args": [
        "--directory",
        "{{Path to the cloned repo",
        "run",
        "mcp-google-cse"
    ],
    "env": {
        "API_KEY": "your-api-key",
        "ENGINE_ID": "your-engine-id"
    }
}

Environment Variables

You can customize the server behavior with these environment variables:

API_KEY (required): Your Google Custom Search API key
ENGINE_ID (required): Your Custom Search Engine ID
SERVICE_NAME (optional): The service name (leave empty if using default "customsearch")
COUNTRY_REGION (optional): Restricts results to documents from a specific country
GEOLOCATION (optional, default "us"): The geolocation of the end-user
RESULT_LANGUAGE (optional, default "lang_en"): The language of search results
RESULT_NUM (optional, default 10): Number of search results to return (1-10)

Usage

The server provides one tool:

google_search

Searches the custom search engine and returns a list of results.

Parameters:

search_term (string, required): The search term, equivalent to the Google search query parameter

Example usage:

google_search("What is MCP after:2024-11-01")

Example result:

[
    {
        "title": "Can someone explain MCP to me? How are you using it? And what ...",
        "link": "https://www.reddit.com/r/ClaudeAI/comments/1h55zxd/can_someone_explain_mcp_to_me_how_are_you_using/",
        "snippet": "Dec 2, 2024 ... Comments Section ... MCP essentially allows you to give Claude access to various external systems. This can be files on your computer, an API, a browser, a ..."
    },
    {
        "title": "Introducing the Model Context Protocol \\ Anthropic",
        "link": "https://www.anthropic.com/news/model-context-protocol",
        "snippet": "Nov 25, 2024 ... The Model Context Protocol (MCP) is an open standard for connecting AI assistants to the systems where data lives, including content repositories, ..."
    }
    // Additional results truncated for brevity
]

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mcp-google-cse" '{"command":"uvx","args":["mcp-google-cse"],"env":{"API_KEY":"","ENGINE_ID":""}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mcp-google-cse": {
            "command": "uvx",
            "args": [
                "mcp-google-cse"
            ],
            "env": {
                "API_KEY": "",
                "ENGINE_ID": ""
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "mcp-google-cse": {
            "command": "uvx",
            "args": [
                "mcp-google-cse"
            ],
            "env": {
                "API_KEY": "",
                "ENGINE_ID": ""
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect