google-search

This MCP server exposes Google search capabilities via a real-time, Playwright-based Google search tool that can be consumed by AI assistants through the MCP interface. It runs locally as a server that accepts search queries and returns structured results including title, link, and snippet, with an option to fetch raw HTML for deeper analysis. The underlying tool supports both headless and headed modes, automatic browser state management to bypass anti-bot checks, and optional HTML retrieval for debugging or analysis. To use it with an AI assistant like Claude, you configure the MCP client to target the google-search MCP server and issue search queries; the server will return a JSON payload containing matching results suitable for downstream reasoning and action.

Prerequisites:

• Node.js and npm (or an alternative Node.js package manager like yarn or pnpm)
• Git (for cloning, if installing from source)

Install from source (recommended):

# Clone the repository
git clone https://github.com/web-agent-master/google-search.git
cd google-search

# Install dependencies
npm install
# Or using yarn
# yarn
# Or using pnpm
# pnpm install

# Compile TypeScript code (if using TS build step)
npm run build
# Or using yarn/pnpm equivalents
# yarn build
# pnpm build

# Link package globally to enable MCP functionality
npm link
# Or using yarn
# yarn link
# Or using pnpm
# pnpm link

Alternate quick start (via npx, without cloning):

npx google-search-mcp

Notes and tips:

• The server is designed to bypass common anti-bot detections by simulating real user behavior, saving and restoring browser state, and occasionally switching between headless and headed modes. This improves reliability for long-running searches.
• Windows users may need to rely on provided .cmd wrappers and ensure PATH resolution for global npm links is correct.
• If you encounter issues with the MCP integration, ensure you’re using the correct MCP command configuration (typically npx google-search-mcp) and that the target environment has network access to perform live Google searches.
• The MCP server can return raw HTML when requested, which is useful for debugging or when the result structure changes due to Google’s UI updates. Use the --get-html and --save-html options in the CLI, and the MCP response will reflect the same data when used via the server.
• For production usage, consider running behind a process manager and ensure you understand rate limits and terms of service for automated search activity.
• If you’re integrating with Claude Desktop, configure the mcpServers entry to point to google-search as shown in the README example; you may need to use npx or node-based execution depending on your environment.