MCP Gemini Web Search

A Model Context Protocol (MCP) server that provides grounded web search and research powered by Google's Gemini models + Google Search grounding, with retries, rate limiting, and health checks.

Features

• web_search tool with dual modes:
  • normal: Fast, single-step grounded search
  • research: Multi-step research with query planning → execution → synthesis
• web_search_batch tool to run up to 20 independent searches in parallel
• health_check tool for metrics (and optional live probe)
• Google Search grounding for accurate, cited results
• Opinionated system instructions that prioritize official documentation for API/library queries
• Resilience features: rate limiting, retries (exponential backoff + jitter), and per-request timeouts
• Configurable models and endpoints (supports custom base URLs via httpOptions.baseUrl)

Installation

Via npx (Recommended)

npx -y mcp-gemini-web

Via npm install

npm install -g mcp-gemini-web
mcp-gemini-web

Environment Variables

• GEMINI_API_KEY or GOOGLE_API_KEY (required): Google AI API key
• GENAI_BASE_URL or GEMINI_BASE_URL (optional): Custom API endpoint base URL
• MODEL (optional): Default model (default: gemini-3-flash-preview)
• REQUEST_TIMEOUT (optional): Default request timeout in ms (default: 60000)

Rate limiting:

• RATE_LIMIT_RPM (optional): Requests per minute (default: 60)
• RATE_LIMIT_MAX_BURST (optional): Max burst capacity (default: 10)

Retries:

• MAX_RETRIES (optional): Max retry attempts (default: 5)
• BASE_RETRY_DELAY (optional): Base delay in ms (default: 1000)
• MAX_RETRY_DELAY (optional): Max delay in ms (default: 60000)
• JITTER_FACTOR (optional): Jitter factor 0-1 (default: 0.1)

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gemini-web": {
      "command": "npx",
      "args": ["-y", "mcp-gemini-web"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Other MCP Clients

The server communicates via stdio using the MCP protocol. Configure your client to run:

npx -y mcp-gemini-web

Usage Examples

Normal Search (Fast)

{
  "tool": "web_search",
  "arguments": {
    "q": "what is Node.js 22 LTS",
    "mode": "normal",
    "verbosity": "normal",
    "include_sources": true
  }
}

Research Mode (Deep)

{
  "tool": "web_search",
  "arguments": {
    "q": "compare axios vs fetch for production Node.js usage",
    "mode": "research",
    "max_steps": 4,
    "research_concurrency": "parallel"
  }
}

Batch Search (Parallel)

{
  "tool": "web_search_batch",
  "arguments": {
    "queries": [
      "Node.js 22 release notes",
      "TypeScript 5.6 new features",
      "Vitest 2 migration guide"
    ],
    "include_sources": false
  }
}

Health Check

{
  "tool": "health_check",
  "arguments": {
    "include_metrics": true,
    "probe": false
  }
}

Health Check (Live Probe)

{
  "tool": "health_check",
  "arguments": {
    "include_metrics": true,
    "probe": true,
    "probe_timeout": 10000
  }
}

Tool Parameters

web_search

• q (string, required): Search query
• mode ("normal" | "research", optional): Default "normal"
• model (string, optional): Model to use (default: MODEL env or gemini-3-flash-preview)
• verbosity ("concise" | "normal" | "detailed", optional): Default "normal"
• max_tokens (number, optional): Overrides verbosity (64–131072)
• max_steps (number, optional): Research steps (1–6, default: 3; only in research mode)
• research_concurrency ("parallel" | "sequential", optional): Default "parallel" (only in research mode)
• include_sources (boolean, optional): Include sources + metadata footer (default: false)
• timeout (number, optional): Per-request timeout in ms (5000–300000)

web_search_batch

• queries (string[], required): 1–20 queries
• model, verbosity, max_tokens, include_sources, timeout: Same meaning as web_search (applies per query)

health_check

• include_metrics (boolean, optional): Default true
• probe (boolean, optional): If true, performs a lightweight API call (default false)
• probe_timeout (number, optional): Probe timeout in ms (1000–30000, default 10000)

Development

# Clone and install
git clone <repository-url>
cd mcp-gemini-web
npm install

# Development mode
npm run dev

# Build
npm run build

# Test
npm test

# Start built version
npm start

License

MIT

Contributing

Pull requests welcome! Please ensure tests pass and follow the existing code style.