SearXNG MCP Server Go
xlionjuan/searxng-mcp-go
Busca web descentralizada para agentes IA via SearXNG
Ver no GitHubServidor 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-go1 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
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 buildworks on Linux, macOS, and other platforms supported by the Go toolchain. - Official distribution: Linux only (x86_64 and arm64). The Homebrew cask
and
goreleaserbuild matrix (goos: [linux]in.goreleaser.yaml) intentionally target Linux. macOS is not packaged — build from source withgo buildif 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 buildfrom 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
| Variable | Required | Default | Description |
|---|---|---|---|
SEARXNG_URL | Yes | — | SearXNG instance URL |
SEARXNG_TIMEOUT | No | 8s | HTTP client timeout (e.g., 8s) |
SEARXNG_MAX_RETRIES | No | 5 | Max retries after initial search attempt |
SEARXNG_ALLOW_GET_FALLBACK | No | 0 | Set 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. |
DEBUG | No | — | 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, orSEARXNG_ALLOW_GET_FALLBACKis set to a value the server cannot parse (or, forSEARXNG_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-fallbackCLI flags, which are validated on the command line and exit with a non-zero status on invalid input.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| MCP client cannot start the server | Binary not found in PATH. Use which searxng-mcp-go and set command to the absolute path in your client config. |
SEARXNG_URL missing | The server has no default SearXNG instance. Set SEARXNG_URL or pass --searxng-url. |
| Connection refused / timeout | SearXNG instance not reachable. Check the URL and network connectivity. SEARXNG_TIMEOUT controls the timeout. |
405 Method Not Allowed or 501 Not Implemented from search | The 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 JSON | SearXNG JSON API not enabled. Ensure search.formats includes json in your SearXNG settings.yml. |
| Empty or invalid query | Queries 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
- Installation and Configuration Guide — User installation and MCP configuration
- MCP Tool Reference — Full tool parameters, response format, error reference
- AGENTS.md — Project documentation for AI agents