Google

You can run a Python-based MCP server that exposes real-time Google search capabilities to AI assistants like Claude. This server lets your AI tools perform local, privacy-conscious searches, retrieves raw HTML when needed, and integrates seamlessly through the MCP protocol for dynamic querying and results.

How to use

To use the server with an MCP client, start the local MCP endpoint that wraps the Google search tooling. The server runs as a stdio MCP service, so you launch it from your environment and point your MCP client at the local process. You will then be able to send search requests and receive structured results that include titles, links, and snippets, with optional access to raw HTML content for debugging or analysis.

Typical usage patterns include initiating a search workflow from your AI assistant, requesting the latest results on a topic, or fetching raw HTML for pages to inspect structure changes. You can also opt into capturing a full-page screenshot when saving HTML content to aid debugging and verification.

How to install

Prerequisites you need before installation:

• Python 3.8+ is required.
• Git is used to clone the repository if you install from source.
• Python dependencies must be installed with a requirements file.
• Playwright browsers should be installed for browser automation.

Step-by-step setup from source or package is shown below. Follow these commands in your terminal:

# Clone the project repository
git clone https://github.com/iwanghc/mcp_web_search.git
cd mcp_web_search

# Install Python dependencies
pip install -r requirements.txt

# Install Playwright browsers
playwright install chromium

# Start the MCP server (stdio mode via Python CLI)
python mcp_server_simple.py

Additional configuration and notes

MCP server configuration is demonstrated by an explicit CLI-based example that integrates with Claude Desktop. This configuration runs the MCP server locally as a Python process and exposes it to the MCP client through standard input/output channels.

Environment variables can be provided to configure access to the model provider or other runtime options. For example, you can supply a model API key via a dotenv file or environment variable, and the client can reference that key when connecting to the MCP endpoint.

If you need to customize startup behavior or debugging, you can enable headed mode, set a remote debugging port, or adjust the browser state handling to optimize anti-bot resilience during development.

Troubleshooting and tips

Common issues include browser startup failures, timeouts when querying the MCP endpoint, and parsing errors when the search results HTML structure changes. Ensure you have the required browser binaries installed, verify network access for local debugging, and check logs for detailed error messages.

To improve stability during development, save and reuse browser state between runs so the anti-bot checks are less frequently triggered. You can also run in headed mode temporarily to observe browser interactions during troubleshooting.

Tools and endpoints referenced

This server exposes tools for performing local Google searches, extracting page HTML, and integrating with MCP clients. The key functions include initiating searches, retrieving parsed results with titles/links/snippets, and optionally returning the raw HTML and screenshots for debugging.

Available tools

google_search

Executes a Google search locally via Playwright, returns results including title, link, and snippet. Supports optional raw HTML retrieval and full-page screenshots for debugging.

html_extractor

Parses and extracts relevant data from the search results HTML, enabling analysis when page structure changes.

fingerprint

Manages browser fingerprinting data to mimic real user behavior and reduce anti-bot detections.

browser_manager

Handles Playwright browser lifecycle, including state saving/restoration and headed/headless mode switching.

mcp_integration

Provides MCP server integration to expose search capabilities to AI assistants like Claude.