Google Search

You can run a Model Context Protocol (MCP) server that performs Google searches via Playwright, bypasses common anti-bot measures, handles CAPTCHAs when needed, and returns structured search results for AI assistants and tooling integrations. This server enables real-time Google search capabilities inside your MCP-enabled workflow.

How to use

You access the Google Search MCP server from an MCP client by launching the server as a standalone process and pointing your client to the MCP endpoint. The server accepts the following practical usage parameters: query (required) to specify your search query; limit (optional) to control how many results you want (default is 10); timeout (optional) to bound the search duration; language (optional) to set the result language (examples include en-US or zh-CN); region (optional) to influence regional results (e.g., com, cn). Use these to tailor searches for your AI assistant’s needs.

Typical usage patterns include: performing a single targeted Google search for a question, streaming or batching results for follow-up analysis, and redesigning prompts based on localized results. When the server detects a CAPTCHA, it will switch to a headed browser so you can manually complete verification, after which the session state is saved to avoid repeated verifications in subsequent searches.

How to install

Prerequisites you need before starting: Node.js (and a package manager such as npm or yarn) installed on your system.

Option 1 — Install globally so you can run the MCP server from anywhere.

$npx -y @mcp-server/google-search-mcp@latest

Option 2 — Set up a project-specific MCP server configuration. Create a project file that defines how to start the server locally.

{
  "mcpServers": {
    "google-search": {
      "command": "npx",
      "args": [
        "-y",
        "@mcp-server/google-search-mcp@latest"
      ]
    }
  }
}

Additional setup and running

Install dependencies and build if you are working from source that requires a build step, then start the server.

yarn install

Build the project before running the server if a build step is provided in your setup.

yarn build

Run the MCP server for use in your MCP client.

yarn start

Using with Cursor and MCP Inspector

If you use a Cursor IDE, add the MCP server as a new MCP connection with the following settings.

Name: google-search
Type: command
Command: npx -y @mcp-server/google-search-mcp@latest

For project-specific usage, place the configuration in a file under your project’s Cursor settings (e.g., .cursor/mcp.json) with the same command and arguments as shown above.

Parameters and behavior

The server accepts these search-related parameters: query (required), limit (optional, default 10), timeout (optional, ms, default 60000), language (optional, e.g., en-US), and region (optional, e.g., com). It uses Playwright to drive a Chromium browser, applies fingerprint spoofing and realistic user interactions to reduce bot-detection risks, automatically handles CAPTCHAs by enabling headed mode for user verification, and persists session state to improve future search efficiency.

Notes

Be mindful of rate limits when performing many searches in a short period. This tool is intended for learning and research and should be used in compliance with Google’s terms of service.

Configuration and advanced topics

Browser state is saved to retain session information across searches. The default state file is named and stored in the user’s home directory, but you can customize the path through parameters if your workflow requires it.

Language and region settings directly influence the language of results and regional availability, for example: English US results use language: en-US and region: com; Japanese results use language: ja-JP and region: co.jp; Chinese (Simplified) results use language: zh-CN and region: cn.

License and disclaimer

This project is released under the MIT license. It is intended for educational and research purposes. Ensure you comply with all applicable terms of service and laws when accessing search engines.

Available tools

antiBotBypass

Implements browser fingerprint spoofing and real-user behavior simulation to avoid bot-detection systems during automated searches.

captchaHandling

Automatically switches to headed mode when a CAPTCHA is encountered to allow user verification and continue the search flow.

statePersistence

Saves the browser session state after verification to reduce repeated verification in future searches.

multiLanguageSearch

Supports language and region variations to fetch search results tailored to language and regional preferences.

mcpIntegration

Provides an MCP-compliant server interface for easy integration with AI assistants and other MCP clients.