searxng-mcp-go/docs/INSTALL.md
XLion d6cf967473
fix: redact search parameters in HTTP errors (#577)
* fix: redact search parameters in HTTP errors

* docs: describe HTTP error URL redaction
2026-08-12 23:57:32 +08:00

10 KiB
Raw Permalink Blame History

Installation and Configuration Guide

User Installation

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

Currently supports Linux only (x86_64 and arm64). macOS is not yet supported.

After installation, find the binary's absolute path — MCP clients often don't inherit your shell PATH:

which searxng-mcp-go

Manual (Download from GitHub Releases)

  1. Visit the Releases page
  2. Download the tarball matching your architecture:
    • Linux amd64: searxng-mcp-go_v<VERSION>_linux_amd64.tar.zst
    • Linux arm64: searxng-mcp-go_v<VERSION>_linux_arm64.tar.zst
  3. Extract and install:
tar --zstd -xvf searxng-mcp-go_v<VERSION>_linux_amd64.tar.zst
mkdir -p ~/.local/bin && mv searxng-mcp-go ~/.local/bin/

Verify Installation

searxng-mcp-go --version

Configuration

SearXNG Instance

A SearXNG instance URL is required — there is no default. Set it via the SEARXNG_URL environment variable or --searxng-url CLI flag.

export SEARXNG_URL=https://your-searxng-instance.example.com

Warning: Using http:// for a non-private SearXNG host triggers a non-suppressible warning on every invocation: "Using HTTP for non-private host. Search queries may be transmitted in clear text. Search results could be intercepted and modified by a MITM attacker."

A host is considered private only if it matches one of the following RFC-grounded criteria (see ADR-003):

  • Hostname: localhost or any subdomain of localhost (e.g., something.localhost)
  • IPv4 address in: 0.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10, 127.0.0.0/8, 169.254.0.0/16, 172.16.0.0/12, 192.0.0.0/24, 192.0.2.0/24, 192.88.99.0/24, 192.168.0.0/16, 198.18.0.0/15, 198.51.100.0/24, 203.0.113.0/24, 224.0.0.0/4, 255.255.255.255/32
  • IPv6 address in: ::, ::1, fc00::/7, fe80::/10, ff00::/8

Prefer HTTPS unless the SearXNG instance is on a private/local network.

Note: The warning suppression is based on syntactic host matching only and does not imply confidentiality for cleartext HTTP.

Max Retries

The default retry count is 5 retries after the initial search attempt. Set SEARXNG_MAX_RETRIES to a non-negative integer (maximum 20); in CLI mode, --max-retries overrides the environment variable. Use --max-retries=0 to disable retries in CLI mode.

Timeout

The default per-request HTTP timeout is 8 seconds. Set SEARXNG_TIMEOUT to a Go duration such as 8s; in CLI mode, --timeout overrides the environment variable. The timeout applies to each individual HTTP request attempt, not to the overall search operation including retries. Zero is rejected (use a positive value or omit to keep the default).

HTTP Proxy

The server honours the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables (and their lowercase equivalents). When running behind a corporate or egress proxy, set these variables in the environment:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.example.com

These are cached after the first proxy evaluation; changing them at runtime has no effect.

In MCP client configuration, add the proxy variables to the env block:

{
  "mcpServers": {
    "searxng": {
      "command": "/home/linuxbrew/.linuxbrew/bin/searxng-mcp-go",
      "env": {
        "SEARXNG_URL": "https://your-searxng-instance.example.com",
        "HTTP_PROXY": "http://proxy.example.com:8080",
        "HTTPS_PROXY": "http://proxy.example.com:8080",
        "NO_PROXY": "localhost,127.0.0.1"
      }
    }
  }
}

POST to GET Fallback

Search requests use POST by default. If POST /search returns 405 Method Not Allowed or 501 Not Implemented, the server returns an actionable error by default instead of silently retrying with GET.

Set SEARXNG_ALLOW_GET_FALLBACK=1 only when you need compatibility with a deployment that rejects POST and you accept the risk: GET sends search parameters in the URL, so queries may be recorded by SearXNG, reverse proxies, CDNs, or access logs. When enabled, the server logs a warning on startup and again whenever the fallback is used. In CLI mode, --allow-get-fallback overrides the environment variable.

Invalid Environment Variable Values

SEARXNG_TIMEOUT, SEARXNG_MAX_RETRIES, and SEARXNG_ALLOW_GET_FALLBACK accept fixed formats (a Go duration, an integer in the range 0–20, and 0/1, respectively). When a value is set to something the server cannot parse — for example SEARXNG_TIMEOUT=abc, SEARXNG_MAX_RETRIES=abc, or SEARXNG_ALLOW_GET_FALLBACK=true — the server writes a warning line to stderr that names the offending variable and value, and then the server falls back to whichever value takes precedence: if a corresponding CLI flag is set (e.g. --timeout 30s, --max-retries 10, --allow-get-fallback), that value is used; otherwise the built-in default is used. The process continues running and does not exit. In MCP stdio mode, most MCP clients do not surface the stderr stream, so end users typically do not see the warning at all.

Values that parse successfully but fall outside the documented range (for example SEARXNG_MAX_RETRIES=-1) are not treated this way — they are rejected as a hard startup error, as described below.

If you need strict validation (for example in CI), prefer the --timeout and --max-retries CLI flags instead of the environment variables. Invalid CLI values follow two distinct paths depending on where they are rejected:

  • Flag parse errors — values the command-line parser cannot interpret at all (for example --timeout=abc) are caught before any search flow runs. The error is reported on stderr, the CLI help is printed, and the process exits with a non-zero status. No search request is issued.

  • Semantic validation errors — values that parse successfully but fall outside the documented range (for example --max-retries=-1, or a value above the maximum allowed retries) are accepted by the parser and only fail later, during configuration validation inside the CLI search flow. The error is reported on stderr, the process exits with a non-zero status, and no CLI help is printed. No search request is issued.

    When these values are set via environment variables (e.g., SEARXNG_TIMEOUT=0), they are also rejected with a clear error — the server exits on startup to prevent silent misconfiguration.

Note: If you provide a custom HTTPClient (for example, when using the library programmatically), the Timeout setting is ignored and the provided client is used as-is. Either set Timeout or supply a custom HTTPClient, not both.


MCP Server Configuration

Basic Execution

In MCP mode, searxng-mcp-go is meant to be launched by an MCP client host (such as an AI agent framework), not run directly in a terminal. The client provides the configured environment variables, starts the process, and sends an MCP JSON-RPC first message on stdin before tool calls are available. The first message may be a legacy initialize request, a server/discover request, or a stateless request carrying params._meta["io.modelcontextprotocol/protocolVersion"].

The server uses stdio transport, meaning it communicates via stdin/stdout after the MCP client starts it.

Stdin Validation

The server reads the first line of stdin and performs a bounded structural MCP check before starting. It accepts the legacy JSON-RPC 2.0 initialize request, the server/discover request, or a stateless request carrying params._meta["io.modelcontextprotocol/protocolVersion"]. This preflight is only a safe structure gate; the MCP SDK performs complete protocol metadata validation:

  • Invalid input (non-MCP input, empty stdin, malformed JSON, or no supported first-message shape): the server prints ERROR: stdin does not contain a valid MCP first message to stderr and exits with code 2.
  • Oversized input (the JSON first-message wire bytes exceed the fixed 1 MiB transport bound; an optional trailing newline delimiter is not counted): treated as invalid — same error and exit code 2.

MCP clients that correctly send any supported first message are not affected.

MCP Client Configuration

Configure the MCP server by adding it to your client's mcpServers. Use the absolute path to the binary — MCP clients often don't inherit your shell PATH.

which searxng-mcp-go
{
  "mcpServers": {
    "searxng": {
      "command": "/home/linuxbrew/.linuxbrew/bin/searxng-mcp-go",
      "env": {
        "SEARXNG_URL": "https://your-searxng-instance.example.com",
        "SEARXNG_TIMEOUT": "8s",
        "SEARXNG_MAX_RETRIES": "5"
      }
    }
  }
}

Add "SEARXNG_ALLOW_GET_FALLBACK": "1" only as a temporary compatibility escape hatch for a deployment that rejects POST /search.

Debug Mode (opt-in, do not enable by default)

Warning: Debug mode writes HTTP request and response details, including the full query text, to stderr in plain text. Do not enable it for production use, shared hosts, or any workload where queries may be sensitive.

To enable debug logging temporarily for troubleshooting, add "DEBUG": "1" to the env block above. Remove it once the issue is diagnosed.

CLI Mode Configuration

When running in CLI mode (with a query argument), command-line flags can be used directly:

# Custom SearXNG server via flag
searxng-mcp-go "query" --searxng-url=https://your-searxng-instance.example.com

# Debug mode via flag
searxng-mcp-go "query" --debug

# HTTP timeout and retry tuning via flags
searxng-mcp-go "query" --timeout=8s --max-retries=5

# GET fallback opt-in via flag
searxng-mcp-go "query" --allow-get-fallback

Set NO_COLOR to any non-empty value, or set TERM=dumb, to print errors without ANSI color escape sequences.

Note: Observable HTTP error messages preserve useful URL path diagnostics but redact URL query parameters to [REDACTED]. This applies to rejected redirects and failed GET fallback requests. Enabling GET fallback can still expose search parameters to upstream servers and intermediary logs.