SearXNG MCP Server in golang (WIP)
  • Go 95.6%
  • Shell 2.4%
  • Python 1.2%
  • Just 0.8%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-30 00:08:19 +08:00
.github chore(deps): update astral-sh/setup-uv action to v10.3.2 (#612) 2026-10-29 23:49:40 +08:00
docs fix: resolve lint failures after tool and SDK updates 2026-10-29 23:57:03 +08:00
internal fix: use CutLast for search endpoint path parsing 2026-10-30 00:06:44 +08:00
searxng-server-test chore(deps): update searxng-server-test/searxng digest to c7f3080 (#591) 2026-09-07 00:28:16 +08:00
testdata test: clarify typed weather fixture fallback boundary (#582) 2026-08-13 03:12:29 +08:00
.env.example docs: align documentation with code behavior (issues #547-#551) (#554) 2026-08-11 05:20:47 +08:00
.gitignore chore: Add coverage.* to .gitignore 2026-07-06 21:26:45 +08:00
.gitmodules add searxng as shallow submodule in searxng-server-test/ 2026-05-20 02:34:16 +08:00
.gitnexusignore gitnexus config 2026-06-14 17:11:55 +08:00
.golangci.yml chore(deps): update dependency go to v1.27.1 (#588) 2026-09-06 23:14:09 +08:00
.goreleaser.yaml ci: move go mod tidy check before GoReleaser and clean up pre-release build path 2026-06-11 04:01:06 +08:00
AGENTS.md docs: remove hard wrapping from AGENTS.md 2026-07-14 05:25:03 +08:00
bench_test.go test: guard benchmark fixture roles (#581) 2026-08-13 02:49:20 +08:00
centralization_drift_test.go chore(deps): update dependency go to v1.27.1 (#588) 2026-09-06 23:14:09 +08:00
CLAUDE.md docs: Create CLAUDE.md with usage instructions 2026-06-11 01:40:14 +08:00
cli.go chore(deps): update dependency go to v1.27.1 (#588) 2026-09-06 23:14:09 +08:00
codecov.yml Fixed 7 doc drifts in 6 files (#530) 2026-07-22 02:46:28 +08:00
concurrency_test.go chore(deps): update dependency go to v1.27.1 (#588) 2026-09-06 23:14:09 +08:00
CONTEXT.md docs: align documentation with code behavior (issues #547-#551) (#554) 2026-08-11 05:20:47 +08:00
CONTRIBUTING.md docs: add CONTRIBUTING.md 2026-06-13 22:40:38 +08:00
e2e_cli_test.go test: avoid hardcoded server URL in CLI boundary tests 2026-06-14 21:42:52 +08:00
e2e_error_test.go feat: add maxLength 500 constraint to query param 2026-06-15 15:55:59 +08:00
e2e_exitcode_test.go fix(deps): update module github.com/modelcontextprotocol/go-sdk to v1.7.0 (#542) 2026-08-02 22:13:27 +08:00
e2e_functional_test.go fix: validation error messages, empty results retry, NO_COLOR, CLI mode detection (#485) 2026-07-14 05:28:09 +08:00
e2e_helper_test.go fix(deps): update module github.com/modelcontextprotocol/go-sdk to v1.7.0 (#542) 2026-08-02 22:13:27 +08:00
e2e_lifecycle_test.go chore(deps): update dependency go to v1.27.1 (#588) 2026-09-06 23:14:09 +08:00
e2e_mcp_test.go chore(deps): update searxng-server-test/searxng digest to c7f3080 (#591) 2026-09-07 00:28:16 +08:00
e2e_mockserver_test.go test: add mock-server network boundary e2e tests 2026-06-14 23:04:05 +08:00
e2e_stress_test.go ci: lint with combined e2e,stress tags, fix 38 findings (#526) 2026-07-21 00:54:23 +08:00
error_path_test.go chore(deps): update dependency go to v1.27.1 (#588) 2026-09-06 23:14:09 +08:00
errors_test.go style: fix lll violations, enable godox and nestif, tighten thresholds 2026-06-08 02:53:26 +08:00
format.go chore(deps): update dependency go to v1.27.1 (#588) 2026-09-06 23:14:09 +08:00
format_sanitize_test.go style: fix lll violations, enable godox and nestif, tighten thresholds 2026-06-08 02:53:26 +08:00
format_test.go chore(deps): update dependency go to v1.27.1 (#588) 2026-09-06 23:14:09 +08:00
fuzz_test.go chore(deps): update dependency go to v1.27.1 (#588) 2026-09-06 23:14:09 +08:00
go.mod Bump to v1.8.2 2026-10-30 00:02:20 +08:00
go.sum fix(deps): update module github.com/modelcontextprotocol/go-sdk to v1.8.0 (#609) 2026-10-29 23:49:32 +08:00
golden_capture_test.go chore(deps): update dependency go to v1.27.1 (#588) 2026-09-06 23:14:09 +08:00
justfile test: run active fuzzing with four workers 2026-08-13 06:05:17 +08:00
LICENSE Add GoReleaser config & release workflow with Homebrew Cask auto-publish 2026-05-22 06:43:16 +08:00
main.go Bump to v1.8.3 2026-10-30 00:08:19 +08:00
main_test.go chore(deps): update dependency go to v1.27.1 (#588) 2026-09-06 23:14:09 +08:00
mcp.go fix: resolve lint failures after tool and SDK updates 2026-10-29 23:57:03 +08:00
mcp_test.go fix: mark search tool as read-only and open-world via ToolAnnotations (#450) 2026-07-02 22:45:57 +08:00
mcp_tool_test.go chore(deps): update dependency go to v1.27.1 (#588) 2026-09-06 23:14:09 +08:00
README.md fix(deps): update module github.com/modelcontextprotocol/go-sdk to v1.7.0 (#542) 2026-08-02 22:13:27 +08:00
search_test.go chore(deps): update dependency go to v1.27.1 (#588) 2026-09-06 23:14:09 +08:00
testhelpers_test.go test: construct retry paths through canonical constructor (#560) 2026-08-11 21:44:11 +08:00

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

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. Any argument activates CLI mode, including standalone flags such as --json, --help, or --version. Run without arguments for MCP server mode.

# 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 and sends an MCP JSON-RPC first message on stdin: a legacy initialize request, a server/discover request, or a stateless request carrying params._meta["io.modelcontextprotocol/protocolVersion"]. The startup preflight performs only a bounded structural check; the MCP SDK performs complete protocol metadata validation. The client 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 Per-request HTTP client timeout (e.g., 8s). Must be positive; zero is rejected.
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: Values that cannot be parsed (e.g., SEARXNG_TIMEOUT=abc) produce a warning on stderr and fall back to the built-in default. The process continues running. For strict validation, use the CLI flags (--timeout, --max-retries, --allow-get-fallback), which exit with a non-zero status on invalid input.

Semantically invalid values (e.g., SEARXNG_TIMEOUT=0, a negative SEARXNG_MAX_RETRIES value, or a value exceeding the allowed maximum) are rejected with an error from both env var and CLI flag paths — the process exits on startup to prevent silent misconfiguration.

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 per-request HTTP 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