h-michael/mcp-gemini-web-search

mcp-gemini-web-search

MCP server for web search using gemini-cli.

Prerequisites

• Node.js 20.6.0+ or Bun 1.0+
• gemini-cli installed and configured

gemini-cli Authentication

This MCP server requires gemini-cli to be authenticated. Choose one of the following methods:

1. Login with Google (OAuth) - Browser-based login (credentials cached locally)
2. Gemini API Key - Set GEMINI_API_KEY environment variable (Get API key)
3. Vertex AI - Set GOOGLE_API_KEY and GOOGLE_CLOUD_PROJECT environment variables
4. Application Default Credentials - Run gcloud auth application-default login

Authentication Priority

Uses first available:

1. GEMINI_API_KEY environment variable
2. GOOGLE_API_KEY environment variable (Vertex AI)
3. Application Default Credentials (gcloud auth)
4. OAuth credentials cache (from previous gemini login)

For detailed authentication setup, see gemini-cli authentication docs.

Installation

npm install
npm run build

Usage

Running the Server

With Node.js:

Development mode (using tsx):

npm run dev

Built version:

npm run build
node dist/index.js

With .env file:

node --env-file=.env dist/index.js

With Bun:

Direct TypeScript execution (no build needed):

bun src/index.ts

Built version:

npm run build
bun dist/index.js

No configuration required for basic usage.

Adding to MCP Client

To use this server with an MCP client (like Claude Desktop), add the following to your MCP settings:

With API Key (using environment variables):

{
  "mcpServers": {
    "gemini-web-search": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-gemini-web-search/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

With .env file:

{
  "mcpServers": {
    "gemini-web-search": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/mcp-gemini-web-search/.env",
        "/absolute/path/to/mcp-gemini-web-search/dist/index.js"
      ]
    }
  }
}

Without API Key (using OAuth or other authentication):

{
  "mcpServers": {
    "gemini-web-search": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-gemini-web-search/dist/index.js"]
    }
  }
}

With Bun (TypeScript direct execution, recommended):

{
  "mcpServers": {
    "gemini-web-search": {
      "command": "bun",
      "args": ["/absolute/path/to/mcp-gemini-web-search/src/index.ts"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

With Bun (built version):

{
  "mcpServers": {
    "gemini-web-search": {
      "command": "bun",
      "args": ["/absolute/path/to/mcp-gemini-web-search/dist/index.js"]
    }
  }
}

Replace /absolute/path/to/mcp-gemini-web-search with the actual path where you cloned this repository.

Configuration (Optional)

Using .env file

Create a .env file in the project root:

cp .env.example .env

Edit .env and set your configuration:

GEMINI_API_KEY=your-api-key-here
RATE_LIMIT_REQUESTS=10
RATE_LIMIT_WINDOW_SECONDS=60

Use --env-file flag to load the .env file:

node --env-file=.env dist/index.js

For MCP usage, add --env-file to the args array (see Adding to MCP Client above).

Using environment variables directly

For MCP usage, configure via the env section in your MCP settings.

For standalone usage:

export GEMINI_API_KEY=your-api-key
npm run dev

Available environment variables:

Authentication:

• GEMINI_API_KEY - Gemini API key (passed to gemini-cli)
• GOOGLE_API_KEY - Google API key for Vertex AI (passed to gemini-cli)
• GOOGLE_CLOUD_PROJECT - Google Cloud project ID for Vertex AI (passed to gemini-cli)

Server Configuration:

• GEMINI_CLI_PATH - Custom path to gemini-cli
• RATE_LIMIT_ENABLED - Enable/disable rate limiting (default: true)
• RATE_LIMIT_REQUESTS - Max requests (default: 10)
• RATE_LIMIT_WINDOW_SECONDS - Time window in seconds (default: 60)
• HEALTH_CHECK_INTERVAL - Health check interval in ms (default: 0/disabled)
• NODE_ENV - Set to 'development' for dev mode

Troubleshooting

gemini-cli not found

Install it globally:

npm install -g gemini-cli

Or specify a custom path via environment variable:

export GEMINI_CLI_PATH=/path/to/gemini

For MCP usage, add it to the env section in your MCP settings:

{
  "mcpServers": {
    "gemini-web-search": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-gemini-web-search/dist/index.js"],
      "env": {
        "GEMINI_CLI_PATH": "/path/to/gemini"
      }
    }
  }
}

Verify installation

gemini --version
which gemini

License

MIT