convez.ai
MCP ServerBusca & PesquisaIntermediário
xlionjuan

SearXNG MCP Server Go

xlionjuan/searxng-mcp-go

Busca web descentralizada para agentes IA via SearXNG

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que integra buscas web via SearXNG, um meta-mecanismo de busca descentralizado. Funciona em modo CLI para uso direto ou MCP stdio para agentes IA em Claude Desktop, Cursor e ferramentas compatíveis. Proxia queries para sua instância SearXNG configurada.

Instalação

$npx convez-ai xlionjuan/searxng-mcp-go

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
3
Acompanhando
0
Saúde
57%
Último commit
há 1 dia
Versão
v1.8.3
Issues abertas
8
Contribuidores
7

Casos de uso

  • Agentes IA com capacidade de busca web em tempo real
  • Integração de busca privada em clientes MCP
  • Automação de pesquisas programáticas com CLI

Veredito

Solução sólida em Go para expor SearXNG como ferramenta MCP. Requer instância SearXNG própria (sem padrão) e é focada em Linux. Bom para quem quer busca web descentralizada e privada em agentes.

README

A tradução para o português deste README ainda está na fila.

searxng-mcp-go

A Model Context Protocol (MCP) server that provides web search via the SearXNG meta-search engine. Designed for AI agents that need web search capabilities. Search queries are proxied through your configured SearXNG instance, which forwards them to its configured search engines according to that instance's settings.

Runs in two modes: CLI for direct terminal use, and MCP stdio for integration with AI clients like Claude Desktop, Cursor, and other MCP-compatible tools.

Requirements

  • A SearXNG instance with API access and JSON output enabled in its settings. The server proxies all search queries to this instance — there is no default.
  • Build & run: Pure Go, no OS-specific imports or build constraints. go build works on Linux, macOS, and other platforms supported by the Go toolchain.
  • Official distribution: Linux only (x86_64 and arm64). The Homebrew cask and goreleaser build matrix (goos: [linux] in .goreleaser.yaml) intentionally target Linux. macOS is not packaged — build from source with go build if you need it.

Installation

Homebrew (Linux, recommended)

brew install --cask xlionjuan/tap/searxng-mcp-go

Currently supports Linux only (x86_64 and arm64). The cask and goreleaser build matrix target Linux. macOS users can go build from source.

Manual (Download from Releases)

Download the latest tarball for your architecture from the Releases page, extract it, and place the binary in your PATH:

tar --zstd -xvf searxng-mcp-go_*.tar.zst
mkdir -p ~/.local/bin && mv searxng-mcp-go ~/.local/bin/

More Installation Details

See docs/INSTALL.md for the detailed installation and MCP configuration guide.

Quick Start

1. Verify the installation

searxng-mcp-go --version

Then try a quick search to confirm the server can reach your SearXNG instance:

SEARXNG_URL=http://localhost:8888 searxng-mcp-go "hello world"

You should see search results printed to the terminal.

2. Configure your MCP client

MCP clients often don't inherit your shell PATH, so use the absolute path to the binary:

which searxng-mcp-go
# → /home/linuxbrew/.linuxbrew/bin/searxng-mcp-go

This is what the mcpServers entry looks like — check your MCP client's documentation for where and how to configure it:

{
  "mcpServers": {
    "searxng": {
      "command": "/home/linuxbrew/.linuxbrew/bin/searxng-mcp-go",
      "env": {
        "SEARXNG_URL": "http://localhost:8888"
      }
    }
  }
}

Replace /home/linuxbrew/.linuxbrew/bin/searxng-mcp-go with the actual path from which.

CLI Usage

When you pass a query or flags, the server runs as a one-shot CLI tool and exits.

# Basic search
searxng-mcp-go "golang programming"

# JSON output (for scripting)
searxng-mcp-go "machine learning" --json

# Filter by time range and language
searxng-mcp-go "AI news" --time_range day --language en

For all available flags, run searxng-mcp-go --help or see docs/INSTALL.md.

MCP Mode

When launched without CLI arguments by an MCP client, the server runs in MCP stdio mode. The client starts the process, sends the required MCP JSON-RPC initialize message on stdin, and then exchanges tool calls over stdin/stdout.

The server exposes a single search tool. For full parameter details, response format, and error reference, see docs/MCP_TOOLS.md.

Environment Variables

VariableRequiredDefaultDescription
SEARXNG_URLYes—SearXNG instance URL
SEARXNG_TIMEOUTNo8sHTTP client timeout (e.g., 8s)
SEARXNG_MAX_RETRIESNo5Max retries after initial search attempt
SEARXNG_ALLOW_GET_FALLBACKNo0Set to 1 to opt in to POST→GET fallback when POST /search returns 405/501. This sends search parameters in the URL and may expose queries in upstream logs.
DEBUGNo—Set to 1 to log search queries and HTTP request/response details in plain text. The server emits a warning to stderr on startup; most MCP clients do not surface it. Avoid using it with sensitive queries.

Priority: CLI flag > environment variable > hardcoded default.

Invalid values: If SEARXNG_TIMEOUT, SEARXNG_MAX_RETRIES, or SEARXNG_ALLOW_GET_FALLBACK is set to a value the server cannot parse (or, for SEARXNG_MAX_RETRIES, to a negative number), the server logs a warning to stderr and falls back to the built-in default. It does not exit. For strict validation of timeout, retry, and GET fallback values, use the --timeout, --max-retries, and --allow-get-fallback CLI flags, which are validated on the command line and exit with a non-zero status on invalid input.

Troubleshooting

SymptomLikely cause
MCP client cannot start the serverBinary not found in PATH. Use which searxng-mcp-go and set command to the absolute path in your client config.
SEARXNG_URL missingThe server has no default SearXNG instance. Set SEARXNG_URL or pass --searxng-url.
Connection refused / timeoutSearXNG instance not reachable. Check the URL and network connectivity. SEARXNG_TIMEOUT controls the timeout.
405 Method Not Allowed or 501 Not Implemented from searchThe SearXNG endpoint or reverse proxy rejected POST /search. Fix the proxy to allow POST. As a compatibility escape hatch, set SEARXNG_ALLOW_GET_FALLBACK=1, but only if you accept that search parameters may appear in URLs and upstream logs.
HTML returned instead of JSONSearXNG JSON API not enabled. Ensure search.formats includes json in your SearXNG settings.yml.
Empty or invalid queryQueries must be non-empty strings. For the full per-parameter rules (time_range, categories, engines, language, pageno, limit), see docs/MCP_TOOLS.md.

More Documentation

Ver o original no GitHub

Bom para

Relacionados