MCP Gemini Grounded Search

★ 8

from cnosuke

A Go-based MCP server providing grounded search functionality using Google's Gemini API.

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys

MCP Gemini Grounded Search

MCP Gemini Grounded Search is a Go-based MCP server that provides grounded search functionality using Google's Gemini API. MCP clients such as Claude Desktop and Claude Code can perform real-time web searches and retrieve up-to-date information with source attribution.

Features

MCP Compliance: JSON-RPC based interface for tool execution per the MCP specification
Grounded Search: Gemini API generates answers with source attributions
Two Transport Modes: stdio (for Claude Desktop / Claude Code) and Streamable HTTP
Flexible Configuration: config file, environment variables, or command-line flags

Using with Docker (Recommended)

docker pull cnosuke/mcp-gemini-grounded-search:latest

docker run -i --rm -e GEMINI_API_KEY="your-api-key" cnosuke/mcp-gemini-grounded-search:latest server

Using with Claude Desktop (Docker)

Add an entry to your claude_desktop_config.json:

{
  "mcpServers": {
    "gemini-search": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GEMINI_API_KEY=your-api-key", "cnosuke/mcp-gemini-grounded-search:latest", "server"]
    }
  }
}

Using with Claude Code (Docker)

claude mcp add-json mcp-gemini-grounded-search '{
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "-e", "GEMINI_API_KEY",
    "-e", "GEMINI_MODEL_NAME",
    "-e", "GEMINI_THINKING_LEVEL",
    "cnosuke/mcp-gemini-grounded-search:latest",
    "server"
  ],
  "env": {
    "GEMINI_MODEL_NAME": "gemini-3.1-pro-preview",
    "GEMINI_THINKING_LEVEL": "LOW",
    "GEMINI_API_KEY": "<your-gemini-api-key>"
  }
}'

Streamable HTTP Mode

The httpserver subcommand starts an HTTP server compatible with the MCP Streamable HTTP transport.

HTTP_AUTH_TOKEN=secret GEMINI_API_KEY=your-key \
  ./bin/mcp-gemini-grounded-search httpserver --config config.yml

# Health check (no auth required)
curl http://localhost:8080/health

# MCP endpoint (auth required)
curl -H "Authorization: Bearer secret" http://localhost:8080/mcp

HTTP-specific settings can be configured entirely via environment variables — no need to put secrets in config.yml.

Command-Line Options

`server` subcommand (stdio)

./bin/mcp-gemini-grounded-search server [options]

Flag	Short	Description
`--config`	`-c`	Path to config file (default: `config.yml`)
`--log`	`-l`	Log file path
`--debug`	`-d`	Enable debug logging
`--api-key`	`-k`	Gemini API key
`--model`	`-m`	Gemini model name
`--thinking-level`		`MINIMAL` / `LOW` / `MEDIUM` / `HIGH`

`httpserver` subcommand (Streamable HTTP)

./bin/mcp-gemini-grounded-search httpserver [options]

Flag	Short	Description
`--config`	`-c`	Path to config file (default: `config.yml`)

All HTTP settings (port, auth_token, etc.) are configured via environment variables or config.yml.

MCP Tools

`search`

Performs a web search using the Gemini API and returns a grounded answer with sources.

Parameters:

Parameter	Type	Required	Description
`question`	string	Yes	Natural language question to search
`max_token`	number	No	Max tokens for the response
`thinking_level`	string	No	Override thinking level for this call

Response:

{
  "text": "Generated answer text",
  "groundings": [
    {
      "title": "Source title",
      "domain": "example.com",
      "url": "https://example.com/article"
    }
  ]
}

Logging

Set log in config.yml or LOG_PATH env var to write logs to a file
If log is empty, no log file is produced
Set debug: true or DEBUG=true for verbose logging

Copy & paste — that's it

docker pull cnosuke/mcp-gemini-grounded-search:latest

docker run -i --rm -e GEMINI_API_KEY="your-api-key" cnosuke/mcp-gemini-grounded-search:latest server

Before it works, you'll need: GEMINI_MODEL_NAMEGEMINI_THINKING_LEVELGEMINI_API_KEY

Requirements

Docker (recommended)

For local development:

Go 1.24 or later
Gemini API key

Building and Running (Go Binary)

# Build
make bin/mcp-gemini-grounded-search

# stdio mode (for Claude Desktop / Claude Code)
./bin/mcp-gemini-grounded-search server --config config.yml

# Streamable HTTP mode
./bin/mcp-gemini-grounded-search httpserver --config config.yml

Using with Claude Desktop (Go Binary)

{
  "mcpServers": {
    "gemini-search": {
      "command": "/path/to/mcp-gemini-grounded-search",
      "args": ["server", "--config", "/path/to/config.yml"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Configuration

config.yml

log: 'path/to/mcp-gemini-grounded-search.log'  # empty = no log output
debug: false

gemini:
  api_key: ''                      # Set via GEMINI_API_KEY env var
  model_name: 'gemini-3.1-pro-preview'
  max_tokens: 5000
  thinking_level: 'LOW'            # Gemini 3.x series: MINIMAL, LOW, MEDIUM, HIGH
  # thinking_budget: 0             # Gemini 2.5 series: token count (0 = disable thinking)

http:
  port: 8080
  endpoint_path: /mcp
  auth_token: ''                   # Set via HTTP_AUTH_TOKEN env var
  allowed_origins: []              # e.g. ['https://example.com'] — empty = allow all
  heartbeat_seconds: 30

Environment Variables

Configuration priority: defaults → config.yml → environment variables

Variable	Description
`GEMINI_API_KEY`	Gemini API key (required)
`GEMINI_MODEL_NAME`	Model name (default: `gemini-3.1-pro-preview`)
`GEMINI_MAX_TOKENS`	Max response tokens (default: 5000)
`GEMINI_THINKING_LEVEL`	`MINIMAL` / `LOW` / `MEDIUM` / `HIGH` (Gemini 3.x)
`GEMINI_THINKING_BUDGET`	Token budget for thinking (Gemini 2.5; integer required)
`GEMINI_QUERY_TEMPLATE`	Custom query template (must contain `%s`)
`HTTP_PORT`	HTTP server port (default: 8080)
`HTTP_AUTH_TOKEN`	Bearer token for MCP endpoint authentication
`HTTP_ENDPOINT_PATH`	MCP endpoint path (default: `/mcp`)
`HTTP_ALLOWED_ORIGINS`	Comma-separated allowed CORS origins
`HTTP_HEARTBEAT_SECONDS`	SSE heartbeat interval in seconds (default: 30)
`LOG_PATH`	Log file path
`DEBUG`	Enable debug logging (`true` or `1`)

MCP Gemini Grounded Search

Features

Using with Docker (Recommended)

Using with Claude Desktop (Docker)

Using with Claude Code (Docker)

Streamable HTTP Mode

Command-Line Options

server subcommand (stdio)

httpserver subcommand (Streamable HTTP)

MCP Tools

search

Logging

Requirements

Building and Running (Go Binary)

Using with Claude Desktop (Go Binary)

Configuration

config.yml

Environment Variables

License

`server` subcommand (stdio)

`httpserver` subcommand (Streamable HTTP)

`search`