MCP Gemini Grounded Search

Um servidor MCP baseado em Go que fornece funcionalidade de pesquisa fundamentada usando a API Gemini do Google.

Documentação

MCP Gemini Grounded Search

O MCP Gemini Grounded Search é um servidor MCP baseado em Go que fornece funcionalidade de busca fundamentada usando a API Gemini do Google. Clientes MCP como Claude Desktop e Claude Code podem realizar buscas na web em tempo real e obter informações atualizadas com atribuição de fontes.

Recursos

Conformidade com MCP: Interface baseada em JSON-RPC para execução de ferramentas conforme a especificação MCP
Busca Fundamentada: A API Gemini gera respostas com atribuição de fontes
Dois Modos de Transporte: stdio (para Claude Desktop / Claude Code) e HTTP Streamable
Configuração Flexível: arquivo de configuração, variáveis de ambiente ou flags de linha de comando

Requisitos

Docker (recomendado)

Para desenvolvimento local:

Go 1.24 ou posterior
Chave da API Gemini

Uso com Docker (Recomendado)

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

Uso com Claude Desktop (Docker)

Adicione uma entrada ao seu 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"]
    }
  }
}

Uso com 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.8-flash",
    "GEMINI_THINKING_LEVEL": "LOW",
    "GEMINI_API_KEY": "<your-gemini-api-key>"
  }
}'

Compilação e Execução (Binário Go)

# 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

Uso com Claude Desktop (Binário Go)

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

Modo HTTP Streamable

O subcomando httpserver inicia um servidor HTTP compatível com o transporte MCP Streamable HTTP.

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

As configurações específicas de HTTP podem ser definidas inteiramente por variáveis de ambiente — não é necessário colocar segredos no config.yml.

Configuração

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.8-flash'
  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

Variáveis de Ambiente

Prioridade de configuração: padrões → config.yml → variáveis de ambiente

Variável	Descrição
`GEMINI_API_KEY`	Chave da API Gemini (obrigatória)
`GEMINI_MODEL_NAME`	Nome do modelo (padrão: `gemini-3.8-flash`)
`GEMINI_MAX_TOKENS`	Máximo de tokens de resposta (padrão: 5000)
`GEMINI_THINKING_LEVEL`	`MINIMAL` / `LOW` / `MEDIUM` / `HIGH` (Gemini 3.x)
`GEMINI_THINKING_BUDGET`	Orçamento de tokens para raciocínio (Gemini 2.5; inteiro obrigatório)
`GEMINI_QUERY_TEMPLATE`	Modelo de consulta personalizado (deve conter `%s`)
`HTTP_PORT`	Porta do servidor HTTP (padrão: 8080)
`HTTP_AUTH_TOKEN`	Token Bearer para autenticação do endpoint MCP
`HTTP_ENDPOINT_PATH`	Caminho do endpoint MCP (padrão: `/mcp`)
`HTTP_ALLOWED_ORIGINS`	Origens CORS permitidas separadas por vírgula
`HTTP_HEARTBEAT_SECONDS`	Intervalo de heartbeat SSE em segundos (padrão: 30)
`LOG_PATH`	Caminho do arquivo de log
`DEBUG`	Ativar log de depuração (`true` ou `1`)

Opções de Linha de Comando

Subcomando `server` (stdio)

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

Flag	Curta	Descrição
`--config`	`-c`	Caminho para o arquivo de configuração (padrão: `config.yml`)
`--log`	`-l`	Caminho do arquivo de log
`--debug`	`-d`	Ativar log de depuração
`--api-key`	`-k`	Chave da API Gemini
`--model`	`-m`	Nome do modelo Gemini
`--thinking-level`		`MINIMAL` / `LOW` / `MEDIUM` / `HIGH`

Subcomando `httpserver` (HTTP Streamable)

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

Flag	Curta	Descrição
`--config`	`-c`	Caminho para o arquivo de configuração (padrão: `config.yml`)

Todas as configurações HTTP (port, auth_token, etc.) são definidas por variáveis de ambiente ou config.yml.

Ferramentas MCP

`search`

Realiza uma busca na web usando a API Gemini e retorna uma resposta fundamentada com fontes.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`question`	string	Sim	Pergunta em linguagem natural para busca
`max_token`	number	Não	Máximo de tokens para a resposta
`thinking_level`	string	Não	Substituir o nível de raciocínio para esta chamada

Resposta:

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

Registro de Logs

Defina log no config.yml ou a variável de ambiente LOG_PATH para gravar logs em um arquivo
Se log estiver vazio, nenhum arquivo de log será gerado
Defina debug: true ou DEBUG=true para logs detalhados

Contribuições

Contribuições são bem-vindas. Por favor, faça um fork do repositório e envie pull requests para melhorias ou correções de bugs. Para mudanças significativas, abra uma issue primeiro para discutir suas ideias.

Licença

Este projeto é licenciado sob a Licença MIT.

Autor: cnosuke ( x.com/cnosuke )

MCP Gemini Grounded Search

Documentação