MCP Tool for Chrome-Based Google Search & Content Retrieval

This MCP utility module is designed to interface with the Claude environment, enabling sophisticated Google searches and the retrieval of visible webpage content by directly commanding the Google Chrome browser instance.

Deployment Instructions

1. Configure Claude Desktop Environment
2. Launch the Claude application on your macOS system.
3. Access the configuration panel via Claude > Settings > Developer > Edit Config.
4. Integrate the following configuration block into your settings file:

{ "mcpServers": { "mcp-browser-google-fetcher": { "command": "npx", "args": [ "-y", "@cmann50/mcp-chrome-google-search" ] } } }

• Effectuate a restart of the Claude Desktop client.

• Initial System Preparation Steps

• Authorization for Accessibility Features

  • Upon the first invocation, you must authorize the necessary macOS accessibility permissions when prompted.
  • Manually navigate to: System Preferences > Security & Privacy > Privacy > Accessibility
  • Ensure the terminal application responsible for executing this tool is explicitly added and activated.

• Enabling Scripting in Chrome

  • Open the Google Chrome application.
  • Navigate to the menu path: View > Developer > Allow JavaScript from Apple Events.
  • Note: This permission setting is persistent and only requires this single configuration action.

Once these prerequisite adjustments are complete, Claude will possess the capability to execute targeted Google queries and systematically pull textual content from resulting URLs via your active Chrome session upon receiving appropriate instructions.

Principal Benefits

• Zero monetary cost associated with executing searches via Google.
• Employs a standard, non-headless Chrome window, minimizing the risk of automated access detection or blocking.
• Because the operation leverages your existing Chrome context, it retains the ability to access content requiring user authentication; Claude can simply open the authenticated URL for content harvesting.

Supported Operating Systems

• ✅ macOS Environment
• ❌ Windows (Not currently compatible)
• ❌ Linux Distributions (Not currently compatible)

Prerequisites for Operation

1. A functioning macOS environment.
2. A pre-installed copy of Google Chrome.
3. Node.js runtime environment, version 20 or newer.

Alternative Invocation Pathways

Direct NPX Execution

bash npx mcp-browser-google-fetcher

Custom Local Build Integration

1. Obtain the source code repository via git checkout.
2. Execute the build script: npm run build.
3. Update the Claude configuration file (ensure the path specified is absolute):

{ "google-tools": { "command": "node", "args": [ "/absolute/path/to/your/checkout/mcp/mcp-chrome-google-search/dist/index.js" ] } }

Local Development Workflow

To validate modifications locally, increment the version number within package.json and run the following command to initiate the local editing mode:

npm install -g .

Subsequently, execute npm run build. The compiled artifacts will populate the dist directory, which Claude actively monitors. Following this, trigger a refresh in Claude Desktop using ctrl-R without requiring a full application restart.

Diagnostic Procedures

Log Stream Monitoring

bash

Observe real-time operational output

tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

Accessing Developer Tools (Debugging Console)

1. Activate developer modes within Claude: bash echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json

2. Launch the built-in DevTools panel within Claude desktop: Command-Option-Shift-i

3. While monitoring the log stream via tail, use ctrl-r in Claude to force a rerun and capture detailed error traces.

Common Issue Resolution

JavaScript Execution Failure in Chrome

If the following error message is observed:

execution error: Google Chrome got an error: Executing JavaScript through AppleScript is turned off. For more information: https://support.google.com/chrome/?p=applescript (12)

Remedy: 1. Open Google Chrome. 2. Navigate to View > Developer. 3. Verify and enable the option: 'Allow JavaScript from Apple Events'.

Failures Related to System Permissions

If Chrome interaction proves unresponsive: 1. Access System Preferences. 2. Navigate to Security & Privacy > Privacy > Accessibility. 3. Confirm that the terminal emulator running the tool is present in the list and its checkbox is marked. 4. Utilize the padlock icon to unlock settings if modifications are necessary.

Technical Implementation Notes

• Relies fundamentally on macOS's AppleScript framework for controlling the Chrome application.
• The automation process is visually observable; users will see Chrome windows opening and navigating.
• Every distinct query typically initiates a new tab within the Chrome session.
• Mechanisms are in place to prune obsolete or inactive tabs periodically to maintain execution efficiency.
• Usage should be restricted to trusted Claude environments, as this grants deep control over the system's browser capabilities.

User Support Structure

• Report any encountered malfunctions by creating a new Issue on the project's GitHub repository.
• When reporting, include specifics regarding your current macOS version and the version of Google Chrome installed.

Licensing Information

This software is distributed under the terms of the MIT License; refer to the accompanying LICENSE file for comprehensive details.

WIKIPEDIA: A headless browser is defined as a web browser devoid of a graphical user interface. These environments permit programmatic command over a web page's rendering process, mirroring the behavior of standard browsers, yet are controlled via command-line interfaces or network protocols. They are invaluable for quality assurance testing because they interpret HTML, apply styling (layout, color, typography), and execute dynamic content like JavaScript and Ajax with the same fidelity as a visible browser, features often absent in simpler testing utilities. Since major updates to Chrome (v59) and Firefox (v56), native API support for remote browser control has superseded older technologies such as PhantomJS.

== Primary Applications of Headless Browsing ==

The chief utilities for employing headless environments include:

• Conducting automated validation checks on contemporary web applications (web testing).
• Generating static image captures of rendered web documents.
• Executing automated test suites for JavaScript libraries.
• Programmatically simulating user interactions with web interfaces.

=== Secondary Applications ===

Headless agents are also effective instruments for advanced web data acquisition (web scraping). Google itself acknowledged in 2009 that headless tools could aid in indexing content on sites heavily reliant on Ajax. Conversely, headless browsers have been associated with misuse:

• Orchestrating Distributed Denial of Service (DDoS) assaults against web servers.
• Artificially inflating advertisement impression counts.
• Automating interactions in ways contrary to site policy, such as credential stuffing.

However, a comprehensive traffic analysis performed in 2018 indicated no clear bias among malicious actors favoring headless agents over conventional browsers for activities like DDoS, SQL injection, or cross-site scripting.

== Standardized Automation Frameworks ==

Because key browser vendors now natively incorporate headless modes through accessible APIs, various software abstractions exist to manage browser automation via a unified command structure. Notable examples include:

• Selenium WebDriver – Adheres strictly to the W3C WebDriver protocol specification.
• Playwright – A library for Node.js offering control over Chromium, Firefox, and WebKit engines.
• Puppeteer – A specialized Node.js library focused on automating Chrome or Firefox instances.

=== Integration within Test Frameworks ===

Several testing platforms incorporate headless browser capabilities into their operational apparatuses:

• Capybara utilizes headless browsing (via WebKit or Headless Chrome) to precisely emulate user actions during protocol execution.
• Jasmine defaults to Selenium but supports switching to WebKit or Headless Chrome for its browser-based tests.
• Cypress, a dedicated frontend testing system.
• QF-Test, a commercial software solution for GUI-based automated testing, often leveraging a headless browser component.

=== Alternative Abstraction Layers ===

An alternative methodology involves using software that exposes browser-like Application Programming Interfaces (APIs). Deno, for instance, integrates browser APIs directly into its core design. For Node.js environments, jsdom offers the most comprehensive implementation. While many of these tools support fundamental browser functions (HTML parsing, cookie management, XHR requests, limited JavaScript execution), they typically refrain from actual DOM rendering and possess restricted support for DOM event handling. Consequently, they generally execute faster than full browser simulations.

== Real-World Deployment Scenarios ==

The primary contexts where headless browser technology excels are:

Test automation for modern, dynamic web applications (web testing). Generating high-fidelity screenshots of complex web pages. Executing scripted tests for frontend JavaScript libraries. Automating intricate sequences of user interactions on web documents.