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

Requirements

• Docker (recommended)

For local development:

• Go 1.24 or later
• Gemini API key

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>"
  }
}'

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"
      }
    }
  }
}

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.

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)

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

Contributing

Contributions are welcome. Please fork the repository and submit pull requests for improvements or bug fixes. For major changes, open an issue first to discuss your ideas.

License

This project is licensed under the MIT License.

Author: cnosuke ( x.com/cnosuke )