Result: Research on ANY topic—coding, tech comparisons, regulations, product reviews, health, finance, travel. Curated answers with sources. Saves tokens. Superior to generic web search.

Installation • Quick Start • How It Works • Examples • Claude Code Skill • FAQ

📋 Last Updates (2026-01-08)

v2.0 - Multi-Language & Detection Overhaul

✅ 4-Stage Completion Detection - SVG thumbs-up → aria-label → text → 40s timeout ✅ Multi-Language Support - Works in DE/EN/NL/ES/FR/IT browser locales ✅ 87% Faster - Average 4s detection (was 2s fixed wait) ✅ AI Mode Availability Check - Detects region restrictions with proxy suggestion ✅ 17 Citation Selectors - Language-agnostic fallback chain ✅ 15 Cutoff Markers - Cleaner content extraction across languages

v1.5 - Persistent browser context, CAPTCHA handling improvements v1.0 - Initial MCP server release

What This Is

An MCP server that connects your code agent (Claude, Cursor, Cline, etc.) to Google AI Mode—Google's AI-powered search that synthesizes information from dozens of web sources into a single, cited answer.

Instead of your agent reading page after page, Google does the heavy lifting. Your agent gets one clean, structured response with inline citations.

The advantage: Free, token-efficient research with grounded sources.

How It Works

Your agent asks a question
         ↓
Server launches stealth browser
         ↓
Google AI Mode searches & synthesizes dozens of sources
         ↓
Server extracts AI answer + citations
         ↓
Converts to clean Markdown with [1][2][3] references
         ↓
Your agent receives final answer (optionally saved to .md file)

The key difference:

Traditional web research:

• Agent searches Google → gets 10 links
• Agent reads 5-10 full pages → thousands of tokens consumed
• Agent synthesizes manually → risks missing details or hallucinating
• You pay for all those tokens

With this server:

• Google AI Mode searches + synthesizes → one request
• Your agent receives one clean, cited answer → minimal tokens
• Google's sources are preserved → verifiable, grounded
• It's free (uses public Google Search)

Why This Matters

Google AI Mode (the udm=50 parameter) makes Google search work like a research assistant. It:

• Reads and analyzes dozens of websites automatically
• Synthesizes findings into structured answers
• Cites every claim with source links
• Handles follow-up context across queries

Your agent gets the benefits without doing the work—or burning the tokens

Installation

Works with any MCP-compatible code agent. Choose your setup:

Claude Code:

claude mcp add google-ai-search npx google-ai-mode-mcp@latest

Codex:

codex mcp add google-ai-search -- npx google-ai-mode-mcp@latest

Linux/WSL users on Codex: If you get a "Missing X-Server" error when trying to show the browser for CAPTCHA solving, use xvfb-run:

{
  "mcpServers": {
    "google-ai-search": {
      "command": "xvfb-run",
      "args": ["-a", "npx", "google-ai-mode-mcp@latest"]
    }
  }
}

Install xvfb if needed: sudo apt-get install xvfb

Cline:

cline mcp add google-ai-search -- npx google-ai-mode-mcp@latest

Gemini:

gemini mcp add google-ai-mode npx -y google-ai-mode-mcp@latest --scope user

VS Code:

code --add-mcp '{"name":"google-ai-search","command":"npx","args":["google-ai-mode-mcp@latest"]}'

Cursor, Windsurf, Zed, or other MCP clients:

Add to your MCP config file:

{
  "mcpServers": {
    "google-ai-search": {
      "command": "npx",
      "args": ["google-ai-mode-mcp@latest"]
    }
  }
}

Cursor uses ~/.cursor/mcp.json, Windsurf and Zed have their own settings files. Check your agent's documentation for the config location

Quick Start

Ask your agent naturally:

"Search Google AI Mode for: Next.js 15 App Router best practices"

"What are the new features in Astro 4.0?"

"Research React Server Components and save the results"

The agent will automatically use the MCP server to query Google AI Mode and return a clean, cited answer.

To save results to a file:

"Search for TypeScript 5.4 features and save it"

Files are saved to platform-specific locations:

• Linux: ~/.local/share/google-ai-mode-mcp/results/
• macOS: ~/Library/Application Support/google-ai-mode-mcp/results/
• Windows: %LOCALAPPDATA%\google-ai-mode-mcp\results\

Filenames: 2026-01-04_15-30-45_typescript_5_4.md

First Run: CAPTCHA Handling

On your first query, Google may show a CAPTCHA to verify you're human. This is normal when the browser profile is created.

If you see a CAPTCHA error:

1. Ask your agent: "Switch to visible mode" or "Turn off headless mode"
2. The browser will open visibly
3. Solve the CAPTCHA manually
4. The server detects the solution automatically and continues
5. Next queries will be headless again

After the first CAPTCHA, searches typically run smoothly. The server uses stealth techniques and a persistent browser profile to minimize future CAPTCHAs

Troubleshooting

Repeated CAPTCHAs:

If Google keeps showing CAPTCHAs:

• Tell your agent: "Use visible browser for this search"
• Add 10-30 second delays between searches
• The server automatically restarts after 3 consecutive CAPTCHAs

Browser won't launch:

Clear the browser profile:

# Linux/macOS
rm -rf ~/.local/share/google-ai-mode-mcp/chrome_profile

# Windows
rmdir /s "%LOCALAPPDATA%\google-ai-mode-mcp\chrome_profile"

Wrong language results:

The server forces English results. If you still get wrong languages, clear the profile (see above).

Missing citations:

Update to the latest version:

npm update -g google-ai-mode-mcp

Configuration (Optional)

The server works out of the box. Advanced users can customize via environment variables:

# Browser settings
export GOOGLE_AI_HEADLESS=true              # Run browser invisibly
export GOOGLE_AI_STEALTH_ENABLED=true       # Use anti-detection techniques

# Timeouts
export GOOGLE_AI_RESPONSE_TIMEOUT=30000     # 30 seconds to get AI response
export GOOGLE_AI_CAPTCHA_TIMEOUT=300000     # 5 minutes to solve CAPTCHA

# CAPTCHA handling
export GOOGLE_AI_CAPTCHA_POLL_INTERVAL=3000 # Check every 3 seconds
export GOOGLE_AI_CAPTCHA_MAX_CONSECUTIVE=3  # Restart after 3 CAPTCHAs
export GOOGLE_AI_CAPTCHA_COOLDOWN_MS=30000  # 30 second cooldown

See .env.example for all options.

Tool Reference

The server exposes one tool: search_ai

Parameters:

• query (required) - Your search question
• headless (optional) - Run browser invisibly (default: true)
• timeout_ms (optional) - Request timeout in milliseconds (default: 120000)
• save_to_file (optional) - Save result to .md file (default: false)
• filename (optional) - Custom filename without .md extension

Returns:

{
  "success": true,
  "markdown": "# AI response with citations [1][2]\n\nSources:\n[1] [Title](url)",
  "sources": [
    { "title": "Source Title", "url": "https://example.com", "domain": "example.com" }
  ],
  "query": "Your query",
  "savedTo": "/path/to/results/file.md"
}

Usage examples:

Basic search:

{ "query": "Rust async patterns 2026" }

Save to file:

{ "query": "Next.js 15 features", "save_to_file": true, "filename": "nextjs-15-guide" }

Visible browser (for CAPTCHA or debugging):

{ "query": "PostgreSQL optimization", "headless": false }

Example Use Case

You need to implement OAuth2 in a framework you've never used before.

Traditional approach:

• Your agent searches Google, gets 10 links
• Reads multiple documentation pages and blog posts
• Consumes thousands of tokens
• May miss important