MCP Gemini Grounded Search

MCP Gemini Grounded Search

MCP Gemini Grounded Search es un servidor MCP basado en Go que proporciona funcionalidad de búsqueda fundamentada utilizando la API de Gemini de Google. Los clientes MCP como Claude Desktop y Claude Code pueden realizar búsquedas web en tiempo real y recuperar información actualizada con atribución de fuentes.

Características

• Cumplimiento MCP: Interfaz basada en JSON-RPC para la ejecución de herramientas según la especificación MCP
• Búsqueda fundamentada: La API de Gemini genera respuestas con atribuciones de fuentes
• Dos modos de transporte: stdio (para Claude Desktop / Claude Code) y HTTP Streamable
• Configuración flexible: archivo de configuración, variables de entorno o banderas de línea de comandos

Requisitos

• Docker (recomendado)

Para desarrollo local:

• Go 1.24 o posterior
• Clave de API de Gemini

Uso con 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 con Claude Desktop (Docker)

Agregue una entrada a su 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 con 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>"
  }
}'

Compilación y ejecución (Binario 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 con Claude Desktop (Binario 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

El subcomando httpserver inicia un servidor HTTP compatible con el 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

Los ajustes específicos de HTTP se pueden configurar completamente mediante variables de entorno — no es necesario poner secretos en config.yml.

Configuración

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

Variables de entorno

Prioridad de configuración: valores predeterminados → config.yml → variables de entorno

Variable	Descripción
GEMINI_API_KEY	Clave de API de Gemini (requerida)
GEMINI_MODEL_NAME	Nombre del modelo (predeterminado: gemini-3.8-flash)
GEMINI_MAX_TOKENS	Máximo de tokens de respuesta (predeterminado: 5000)
GEMINI_THINKING_LEVEL	MINIMAL / LOW / MEDIUM / HIGH (Gemini 3.x)
GEMINI_THINKING_BUDGET	Presupuesto de tokens para pensamiento (Gemini 2.5; se requiere entero)
GEMINI_QUERY_TEMPLATE	Plantilla de consulta personalizada (debe contener %s)
HTTP_PORT	Puerto del servidor HTTP (predeterminado: 8080)
HTTP_AUTH_TOKEN	Token Bearer para autenticación del endpoint MCP
HTTP_ENDPOINT_PATH	Ruta del endpoint MCP (predeterminado: /mcp)
HTTP_ALLOWED_ORIGINS	Orígenes CORS permitidos separados por comas
HTTP_HEARTBEAT_SECONDS	Intervalo de latido SSE en segundos (predeterminado: 30)
LOG_PATH	Ruta del archivo de registro
DEBUG	Habilitar registro de depuración (true o 1)

Opciones de línea de comandos

Subcomando server (stdio)

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

Bandeira	Corta	Descripción
--config	-c	Ruta al archivo de configuración (predeterminado: config.yml)
--log	-l	Ruta del archivo de registro
--debug	-d	Habilitar registro de depuración
--api-key	-k	Clave de API de Gemini
--model	-m	Nombre del modelo de Gemini
--thinking-level		MINIMAL / LOW / MEDIUM / HIGH

Subcomando httpserver (HTTP Streamable)

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

Bandeira	Corta	Descripción
--config	-c	Ruta al archivo de configuración (predeterminado: config.yml)

Todos los ajustes HTTP (port, auth_token, etc.) se configuran mediante variables de entorno o config.yml.

Herramientas MCP

search

Realiza una búsqueda web utilizando la API de Gemini y devuelve una respuesta fundamentada con fuentes.

Parámetros:

Parámetro	Tipo	Requerido	Descripción
question	string	Sí	Pregunta en lenguaje natural para buscar
max_token	number	No	Máximo de tokens para la respuesta
thinking_level	string	No	Anular el nivel de pensamiento para esta llamada

Respuesta:

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

Registro

• Establezca log en config.yml o la variable de entorno LOG_PATH para escribir registros en un archivo
• Si log está vacío, no se genera ningún archivo de registro
• Establezca debug: true o DEBUG=true para un registro detallado

Contribuciones

Las contribuciones son bienvenidas. Por favor, haga un fork del repositorio y envíe solicitudes de extracción para mejoras o correcciones de errores. Para cambios importantes, abra primero un issue para discutir sus ideas.

Licencia

Este proyecto está licenciado bajo la Licencia MIT.

Autor: cnosuke ( x.com/cnosuke )