@lohzi97/gemini-search-mcp

v0.2.0

Published

4 days ago

An MCP server that wraps Google Gemini CLI for web search capabilities

0High
0Medium
0Low

lohzi97

mcp model-context-protocol gemini research firecrawl web-scraping ai-agent

Gemini Search MCP

A Model Context Protocol (MCP) server that wraps the Google Gemini CLI for powerful web search capabilities.

Overview

Gemini Search MCP is an npm package that exposes two search tools to MCP-compliant clients (Claude Desktop, Cursor, etc.). Unlike standard search tools that return shallow snippets, this server acts as a Sub-Agent Orchestrator that:

Spawns an autonomous Gemini CLI instance
Executes live Google Searches via Grounding
Fetches and analyzes web content for comprehensive research
Produces a structured research report with citations

Key Features

Two Research Modes: search (quick single-round) and deep_search (multi-round with verification)
Smart Web Fetching: Leverages Gemini's built-in web capabilities to retrieve and analyze content
Optional Enhancement: Can integrate Firecrawl for JavaScript-rendered sites when available
Dual Transport: Supports both stdio (Claude Desktop) and HTTP (remote clients)
Configurable: Environment variables for model selection, timeouts, and more

Architecture

User / IDE → Main AI → gemini-search-mcp → Gemini CLI → Google Search + Web Fetch

The package creates a dedicated configuration directory with project-level Gemini CLI settings, ensuring isolated configuration. When Gemini CLI runs from this directory, it can use built-in web tools or optionally connect to Firecrawl if configured.

Prerequisites

Node.js 22+ LTS - Required for npm package installation
Gemini CLI - Install via npm install -g @google/gemini-cli
Gemini CLI Authentication - Run gemini auth login or set GEMINI_API_KEY
MCP Client - Claude Desktop, Cursor, or any MCP-compliant client

Installation

# Install globally via npm
npm install -g @lohzi97/gemini-search-mcp

# First time setup: Install and authenticate Gemini CLI
npm install -g @google/gemini-cli
gemini auth login  # Opens browser for OAuth

# (Optional) Set Firecrawl API key for enhanced JS rendering on complex sites
export FIRECRAWL_API_KEY=your_firecrawl_api_key

Usage

Starting the Server

Stdio mode (for Claude Desktop):

gemini-search-mcp

HTTP mode (for remote clients):

MCP_SERVER_PORT=3000 gemini-search-mcp-http

Claude Desktop Configuration

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gemini-search": {
      "command": "gemini-search-mcp",
      "args": [],
      "env": {
        "FIRECRAWL_API_KEY": "${FIRECRAWL_API_KEY}",
        "GEMINI_MODEL": "gemini-2.5-flash"
      }
    }
  }
}

Note: FIRECRAWL_API_KEY is optional - remove if not using Firecrawl.

Claude Code (CLI) Configuration

Method 1: CLI Command

claude mcp add --transport stdio gemini-search \
  --env GEMINI_MODEL=gemini-2.5-flash \
  -- gemini-search-mcp

Add --env FIRECRAWL_API_KEY=your-key if you want to use Firecrawl.

Method 2: Manual Configuration

Add to your config at ~/.claude.json (recommended) or ~/.claude/mcp_servers.json:

{
  "mcpServers": {
    "gemini-search": {
      "command": "gemini-search-mcp",
      "env": {
        "GEMINI_MODEL": "gemini-2.5-flash"
      }
    }
  }
}

Add "FIRECRAWL_API_KEY": "your-key" if you want to use Firecrawl.

Note: Some documentation incorrectly mentions ~/.config/claude-code/mcp_servers.json - this location is not recognized by Claude Code.

To verify: In Claude Code, ask "List available MCP tools" to confirm search and deep_search appear.

Using the Tools

This MCP server provides three tools for different use cases:

1. `search` - Quick Single-Round Search

Best for simple queries that don't require multiple iterations.

Parameters:

query (string, required): The search query or question

Example:

Please search for the current population of Tokyo.
Use the search tool.

2. `deep_search` - Multi-Round Iterative Search with Verification

Best for complex topics requiring thorough verification and server-orchestrated iterations.

Parameters:

topic (string, required): The research question or topic
maxIterations (number, optional): Maximum verification rounds (default: 5, max: 10)

Example:

Please research the impact of AI on healthcare in 2024.
Use deep_search tool with maxIterations of 5.

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | GEMINI_MODEL | gemini-2.5-flash | Main Gemini model for search and deep_search | | SECONDARY_GEMINI_MODEL | gemini-2.5-flash | Secondary/faster model for lightweight tasks (JSON correction) | | GEMINI_SEARCH_TIMEOUT | 300000 | Max wait time in milliseconds | | GEMINI_SYSTEM_PROMPT | built-in | Custom system prompt template | | DEEP_SEARCH_MAX_ITERATIONS | 5 | Max verification rounds for deep_search | | MCP_SERVER_PORT | 3000 | HTTP server port | | DEBUG | false | Enable verbose logging | | FIRECRAWL_API_KEY | none | Optional Firecrawl API key | | FIRECRAWL_API_URL | none | Optional URL for self-hosted Firecrawl |

See .env.example for all available options.

Configuration Directory

The package creates ~/.config/gemini-search-mcp/ (Linux) or platform-appropriate equivalent containing:

~/.config/gemini-search-mcp/
└── .gemini/
    └── settings.json  # Generated from template, may include Firecrawl MCP if configured

How It Works

User calls search or deep_search tool from their AI client
gemini-search-mcp receives the request and spawns Gemini CLI
Gemini CLI runs from config directory with its own isolated settings
Gemini CLI uses Google Search and built-in web tools to research the topic
Results are returned as structured JSON to the main AI

Troubleshooting

Gemini CLI Not Found

Error: gemini command not found

Solution: Install Gemini CLI via npm install -g @google/gemini-cli

Firecrawl Configuration

Firecrawl is optional and not required for basic functionality. If you choose to use it:

Set FIRECRAWL_API_KEY for cloud API or FIRECRAWL_API_URL for self-hosted
Ensure your account has available credits
The package will use Gemini's built-in web tools if Firecrawl is unavailable

Timeout Errors

Increase GEMINI_SEARCH_TIMEOUT for complex queries:

export GEMINI_SEARCH_TIMEOUT=600000  # 10 minutes

Debug Mode

Enable verbose logging:

DEBUG=true gemini-search-mcp

Development

# Clone repository
git clone https://github.com/your-username/gemini-search-mcp.git
cd gemini-search-mcp

# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev

# Link for testing
npm link

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to the main repository.

License

MIT License - see LICENSE for details.

Acknowledgments

Google Gemini CLI - The underlying CLI tool
Model Context Protocol - The protocol specification