Imported from reason-machines/mcp-skills (skills/gemini-search-mcp-web-search/SKILL.md). Install upstream with npx skills add reason-machines/mcp-skills --skill gemini-search-mcp-web-search. Copyright stays with the author.

gemini-search-mcp Web Search Skill

Skill by ara.so — MCP Skills collection.

Overview

gemini-search-mcp is an MCP server that provides real-time web search capabilities to AI agents (Claude Desktop, Cursor, Windsurf, etc.) using Google's AI Mode powered by Gemini. It bypasses traditional search API limitations by using Chrome DevTools Protocol (CDP) to execute searches through a real browser, giving unlimited, free access to Google Search results without requiring API keys.

The server exposes two MCP tools:

• web_search(query) - Search the web and get synthesized answers grounded in real-time results
• ask(prompt) - General questions where AI Mode auto-decides whether to search

Additionally, it can run as an OpenAI-compatible API server for non-MCP clients.

Installation

Basic Installation

pip install -e .

With Undetected ChromeDriver (CAPTCHA Resistance)

pip install -e '.[undetected]'

Requirements

• Python 3.10+
• Chrome, Edge, or Chromium browser installed
• No API keys required

MCP Server Setup

Claude Code

claude mcp add gemini-search -- gemini-search-mcp

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "gemini-search": {
      "command": "gemini-search-mcp",
      "args": [],
      "env": {
        "HEADLESS": "1",
        "BROWSER_CHANNEL": "chrome"
      }
    }
  }
}

Cursor / Windsurf

Add to your MCP settings (.cursor/mcp.json or similar):

{
  "mcpServers": {
    "gemini-search": {
      "command": "gemini-search-mcp",
      "args": []
    }
  }
}

Running as OpenAI-Compatible API

Start the server:

gemini-search --port 8080

Use with any OpenAI-compatible client:

import openai

client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"
)

response = client.chat.completions.create(
    model="gemini-search",
    messages=[
        {"role": "user", "content": "What are the latest AI developments in 2026?"}
    ]
)

print(response.choices[0].message.content)

# cURL example
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-search",
    "messages": [{"role": "user", "content": "Bitcoin price today"}]
  }'

Configuration

Environment Variables

Example with Custom Configuration

{
  "mcpServers": {
    "gemini-search": {
      "command": "gemini-search-mcp",
      "args": [],
      "env": {
        "HEADLESS": "1",
        "BROWSER_CHANNEL": "msedge",
        "GEMINI_SEARCH_USER_DATA_DIR": "/home/user/.cache/gemini-search-profile",
        "GEMINI_SEARCH_PROXY_SERVER": "socks5://127.0.0.1:7897"
      }
    }
  }
}

Using the MCP Tools

web_search Tool

Use when you need real-time web information:

# In an MCP client context, the agent would call:
# web_search("latest AI regulation news 2026")

# Returns synthesized answer like:
# "The EU AI Act enforcement began on June 1, 2026, requiring..."

Example queries:

• web_search("current weather in Tokyo")
• web_search("latest SpaceX launch date")
• web_search("Python 3.13 new features")
• web_search("best laptop 2026 under $1000")

ask Tool

Use for general questions where AI Mode decides if web search is needed:

# ask("what is 1847 * 293")
# Returns: "541171" (computed without web search)

# ask("who won the latest Formula 1 race")
# Triggers web search and returns current results

Common Patterns

Persistent Profile for CAPTCHA Avoidance

If Google shows CAPTCHA for temporary profiles, create a persistent profile:

# First run: visible mode, solve CAPTCHA if needed
mkdir -p ~/.local/share/gemini-search-mcp/chrome-profile
gemini-search --no-headless --user-data-dir ~/.local/share/gemini-search-mcp/chrome-profile

Then configure for headless reuse:

{
  "mcpServers": {
    "gemini-search": {
      "command": "gemini-search-mcp",
      "args": [],
      "env": {
        "GEMINI_SEARCH_USER_DATA_DIR": "/home/user/.local/share/gemini-search-mcp/chrome-profile",
        "HEADLESS": "1"
      }
    }
  }
}

Using with Proxy

export GEMINI_SEARCH_PROXY_SERVER="socks5://127.0.0.1:7897"
gemini-search-mcp

Connect to Existing Chrome Instance

Launch Chrome with remote debugging:

# Linux/Mac
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=C:\temp\chrome-profile

Configure MCP server to use it:

{
  "mcpServers": {
    "gemini-search": {
      "command": "gemini-search-mcp",
      "args": [],
      "env": {
        "CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

Docker Deployment

# Using docker-compose
docker compose up -d

# Access at http://localhost:8080

Create docker-compose.yml:

version: '3.8'
services:
  gemini-search:
    build: .
    ports:
      - "8080:8080"
    environment:
      - HEADLESS=1
      - BROWSER_CHANNEL=chrome
    command: gemini-search --port 8080 --host 0.0.0.0

Troubleshooting

CAPTCHA Issues

Problem: Google shows /sorry/ CAPTCHA page

Solution 1: Use persistent profile (see above)

Solution 2: Try undetected-chromedriver backend:

pip install -e '.[undetected]'

# Test first
python scripts/uc_google_probe.py --out-json uc-probe.json

# If probe shows ok=true and captcha=false, use it
gemini-search-mcp --browser-backend undetected

Solution 3: Use a different browser channel:

export BROWSER_CHANNEL=msedge
gemini-search-mcp

Browser Launch Failures

Problem: Chrome fails to start

Solutions:

• Verify Chrome is installed: google-chrome --version or chromium --version
• Try different browser: export BROWSER_CHANNEL=chromium
• Use visible mode for debugging: export HEADLESS=0
• Check CDP port isn't in use: lsof -i :19250

Connection Issues

Problem: MCP client can't connect to server

Solutions:

• Check server is running: ps aux | grep gemini-search
• Verify stdio communication (MCP uses stdio, not HTTP)
• Check logs in Claude Desktop: ~/Library/Logs/Claude/ (Mac) or %APPDATA%\Claude\logs (Windows)
• Restart Claude Desktop after config changes

Rate Limiting

Problem: Getting throttled despite "unlimited" claim

Solutions:

• The tool avoids rate limits via real Chrome fingerprint
• If throttled, you may have network/IP issues
• Try with proxy: export GEMINI_SEARCH_PROXY_SERVER=socks5://127.0.0.1:7897
• Ensure using real Chrome, not chromium-headless-shell

Slow Response Times

Problem: Searches take longer than expected ~1.5s average

Solutions:

• First request is slower (browser startup)
• Use persistent browser via CDP_URL for faster subsequent requests
• Check network latency to Google
• Reduce proxy overhead if using one

DOM Structure Changes

Problem: Search results not parsing correctly

Solutions:

• Google may have updated their AI Mode DOM structure
• Check for project updates: git pull origin main
• Report issues on GitHub with example query
• Use --no-headless to visually inspect what Chrome sees

Advanced Usage

Custom Search Parameters

The server uses Google's AI Mode endpoint internally. For advanced control:

# When calling from Python code (not common for MCP usage)
from gemini_search_mcp import search

result = search.web_search(
    query="Python best practices 2026",
    # Additional parameters handled internally
)

Multiple Concurrent Searches

Each MCP tool call is independent. The server handles concurrency:

# AI agent can make multiple calls
# web_search("topic A")
# web_search("topic B")
# Results arrive as they complete

Integration with LangChain

from langchain.tools import Tool
import requests

def gemini_search(query: str) -> str:
    response = requests.post(
        "http://localhost:8080/v1/chat/completions",
        json={
            "model": "gemini-search",
            "messages": [{"role": "user", "content": query}]
        }
    )
    return response.json()["choices"][0]["message"]["content"]

search_tool = Tool(
    name="GeminiWebSearch",
    func=gemini_search,
    description="Search the web using Google AI Mode for current information"
)

Key Differences from Alternatives

• vs Tavily/SerpAPI: No API key, no cost, no quotas
• vs Grok MCP: Uses Google Search instead of X.ai, no API key needed
• vs Direct HTTP: Avoids TLS fingerprint detection via real Chrome browser
• vs Browser automation: Optimized CDP approach, faster than Selenium