Self-hosted SearXNG metasearch gateway with a built-in MCP server (HTTP mode, no local npx)
  • Go 96.7%
  • Dockerfile 3.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Jens Lewald 48cf8b4ad8 auth-gateway: fix open redirect for unregistered clients + expire pending auth codes
- Discard client-supplied redirect_uri for unregistered clients (prevents
  open redirect / credential harvesting)
- Pending auth codes expire (600s) and are pruned; expired codes rejected
- 3 regression tests; 19/19 green, go vet clean, -race passes
2026-08-20 22:18:49 +02:00
auth-gateway auth-gateway: fix open redirect for unregistered clients + expire pending auth codes 2026-08-20 22:18:49 +02:00
docs hybrid-auth doc: neutralize internal IP in production notes (no infra leak in public repo) 2026-08-20 20:56:46 +02:00
licenses Add third-party licenses (SearXNG AGPL-3.0, mcp-searxng MIT) + attribution section in README 2026-08-20 17:53:28 +02:00
mcp Clean up comments: remove npx/no-local jargon and German fragments from Dockerfiles & compose 2026-08-20 18:07:04 +02:00
searxng Clean up comments: remove npx/no-local jargon and German fragments from Dockerfiles & compose 2026-08-20 18:07:04 +02:00
.env.example auth-gateway: audit log (JSONL), daily per-key quotas, RFC7009 token revoke + 13 unit tests; docs/env updated 2026-08-20 19:54:36 +02:00
.gitignore SearXNG Gateway with built-in MCP stack (no local npx) 2026-08-20 17:43:57 +02:00
docker-compose.auth.yml auth-gateway: add DCR (RFC 7591), persistent token store (auth-data volume), DNS-rebinding/Origin guard, network isolation override + unit tests (6 passing) 2026-08-20 19:14:03 +02:00
docker-compose.yml auth-gateway: audit log (JSONL), daily per-key quotas, RFC7009 token revoke + 13 unit tests; docs/env updated 2026-08-20 19:54:36 +02:00
LICENSE SearXNG Gateway with built-in MCP stack (no local npx) 2026-08-20 17:43:57 +02:00
README.md README: neutralize internal Forgejo URL in quickstart (no infra leak in public repo) 2026-08-20 22:09:43 +02:00
settings.yml SearXNG Gateway with built-in MCP stack (no local npx) 2026-08-20 17:43:57 +02:00

Private Web Search for Your AI Agents

Run your own private, self-hosted web search engine as a single Docker Compose stack — complete with a ready-made endpoint your AI assistant can talk to.

Out of the box you get:

  • 🔍 SearXNG — a privacy-respecting metasearch engine (aggregates Google, Bing, DuckDuckGo and many more, without the trackers).
  • 🔌 An MCP endpoint — the standard protocol AI agents (Claude, Hermes, Cursor,…) use. Wire it up and your agent can search the web through your instance.

Everything runs in one stack. No accounts, no API keys, no external search-SaaS billing. Just search, privately, on your own hardware.

MIT — free to use, adapt and self-host. Contributions welcome.


⚠️ Read this before exposing it to a network

The MCP endpoint starts without authentication (MCP_HTTP_HARDEN=false) so your first docker compose up just works. Anyone who can reach the port can search.

Before exposing the stack on a LAN or the public internet, enable authentication: set MCP_HTTP_HARDEN=true, MCP_AUTH_TOKEN, and MCP_ALLOWED_HOSTS (details in Quick start → Configure and Hardening).


Quick start

You need Docker with the Compose plugin (Docker Desktop or Docker Engine ≥ 20.10). No Node.js, no npm, nothing else.

1. Configure

# Clone the public repo from your Git hosting platform (e.g. GitHub).
# Replace <OWNER>/<REPO> with your actual path.
git clone https://github.com/<OWNER>/<REPO>.git
cd <REPO>

cp .env.example .env

Open .env and set at least SEARXNG_SECRET:

openssl rand -hex 32    # put the output into SEARXNG_SECRET in .env

2. Start

docker compose up -d --build

That's it. Three containers start (search engine, cache, MCP endpoint). The first --build takes a minute or two while the images are compiled.

3. Is it running?

docker compose ps
# expect all three containers "healthy"/"running"

You can browse your search engine at http://localhost:8881 and try a query.


Connect your AI agent

The endpoint speaks the standard MCP Streamable HTTP transport, so any MCP-capable agent can use it. The exact config file and field names depend on your agent — the following are the common ones.

Note on auth: the headers.Authorization: Bearer … snippet below works in agents that let you set a custom HTTP header (Claude Code, VS Code, Cursor, Hermes, …). It is not supported by every client (e.g. Claude Desktop has no field for a custom header). See Hardening.

Claude Code

// ~/.claude.json  (or `claude mcp add --transport http searxng <url> --header "Authorization: Bearer ..."`)
{
  "mcpServers": {
    "searxng": {
      "type": "http",
      "url": "http://<your-host>:8096/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

VS Code / Cursor

// .vscode/mcp.json  or  .cursor/mcp.json
{
  "mcpServers": {
    "searxng": {
      "type": "http",
      "url": "http://<your-host>:8096/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

Hermes (config.yaml)

mcp_servers:
  searxng:
    url: http://<your-host>:8096/mcp
    connect_timeout: 30
    timeout: 120
    headers:
      Authorization: "Bearer <MCP_AUTH_TOKEN>"

OpenCode

OpenCode can use either an API key as a request header or OAuth (auto-detected unless disabled). With the built-in Bearer token, use a remote server with headers and oauth: false:

// opencode.json
{
  "mcp": {
    "servers": {
      "searxng": {
        "type": "remote",
        "url": "https://<your-host>:8096/mcp",
        "oauth": false,
        "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
      }
    }
  }
}

With an OAuth-enabled gateway (see the Hybrid auth gateway design), just point at the URL and leave oauth on — OpenCode does PKCE, token refresh and dynamic client registration automatically:

{
  "mcp": {
    "servers": {
      "searxng": { "type": "remote", "url": "https://mcp.example.com/mcp" }
    }
  }
}

Claude Desktop

Claude Desktop supports the Streamable HTTP transport but its settings file has no field for a custom Authorization header. Options:

  • Run with MCP_HTTP_HARDEN=false (no token) and protect the endpoint at the network / reverse-proxy layer instead (recommended) — see Reverse proxy + Basic Auth.
  • Or use a reverse proxy that injects the Authorization header / handles auth itself.

Which agents can use the built-in Bearer token?

The built-in MCP_HTTP_HARDEN=true + MCP_AUTH_TOKEN mechanism is a plain Bearer HTTP header. Whether it works depends on whether your client lets you set a custom HTTP header:

Client Custom Authorization header? OAuth? Recommended auth
Claude Code ✅ yes (type:"http" + headers) ✅ built-in Bearer, or OAuth
VS Code ✅ yes (headers) ✅ built-in Bearer, or OAuth
Cursor ✅ yes (headers) ✅ (known bugs w/ OAuth discovery) built-in Bearer, or OAuth
Hermes ✅ yes (headers) ~ built-in Bearer
OpenCode ✅ yes (headers + oauth:false) ✅ (PKCE + DCR built-in) built-in Bearer, or OAuth
Claude Desktop ❌ no field for custom header ✅ OAuth gateway, or reverse-proxy Basic Auth
ChatGPT ❌ (no custom header) ✅ OAuth gateway
Other MCP clients depends on the client varies check its docs

For any client without custom-header support, put the endpoint behind a reverse proxy that adds HTTP Basic Auth (or an IP allowlist) — that works with every client, because it acts on the plain HTTP transport, not on the MCP protocol. See below.

Looking for the universal solution? A hybrid auth gateway (OAuth for clients like Claude Desktop / ChatGPT, plus an API-key fallback for everyone else) is the way to cover every client in one deployment. It is implemented and verified — see docs/hybrid-auth-gateway.md and enable it with:

docker compose -f docker-compose.yml -f docker-compose.auth.yml --profile auth up -d --build

The auth override also removes mcp-searxng's public port, so the endpoint is only reachable through the gateway.

The endpoint exposes these tools:

Tool What it does
searxng_web_search search the web
searxng_search_suggestions autocomplete suggestions
searxng_instance_info info about the instance
web_url_read fetch and read the text of a page

Now simply ask your agent to search — it will query your private instance.


Configuration reference

Most people only change the secrets. These environment variables (in .env) control everything:

Variable Default Purpose
SEARXNG_PORT 8881 Host port for the search UI / API
SEARXNG_BASE_URL (unset) Public URL, e.g. https://search.example.com — set if you put it behind a domain so result links are correct
SEARXNG_SECRET (required) Privacy secret for the search engine
MCP_PORT 8096 Host port for the MCP endpoint
MCP_HTTP_HARDEN false Require a Bearer token on the MCP endpoint
MCP_AUTH_TOKEN (only if hardening) Token your agent sends
MCP_ALLOWED_ORIGINS * Allowed browser origins (safe as * for non-browser agents)
MCP_ALLOWED_HOSTS localhost:8096,127.0.0.1:8096 Host names allowed to reach the MCP endpoint

Set this in .env before exposing the stack on a network:

MCP_HTTP_HARDEN=true
MCP_AUTH_TOKEN=<a long random string>     # openssl rand -hex 24
MCP_ALLOWED_HOSTS=your-host:8096,search.example.com:8096

Two things to know:

  1. MCP_HTTP_HARDEN=true requires MCP_AUTH_TOKEN and MCP_ALLOWED_ORIGINS. If they're missing the MCP container won't start — see Troubleshooting.
  2. MCP_ALLOWED_HOSTS must contain the exact host name (with port) your agent sends as the Host: header. A wildcard does not work here. If it's missing, requests fail with Invalid Host header. Add every host/port you connect from.

Troubleshooting

The MCP container keeps restarting / never turns healthy The most common cause: hardening is on but the token is missing.

Failed to start server: MCP_HTTP_HARDEN=true requires MCP_HTTP_AUTH_TOKEN to be set.

→ Turn MCP_HTTP_HARDEN off, or set MCP_AUTH_TOKEN and MCP_ALLOWED_ORIGINS.

"Invalid Host header: :" The endpoint rejects a host that isn't in MCP_ALLOWED_HOSTS. Add the exact host you connect from (with port).

To inspect what's happening:

docker compose logs mcp-searxng
docker compose ps

How it works (briefly)

Three containers on an internal Docker network — only the ports you publish are reachable:

your agent
   │  MCP over HTTP (port 8096)
   ▼
mcp endpoint   ──►   search engine (port 8881)   ──►   cache (internal)
  • search engine — SearXNG, with our config baked in.
  • cache — Valkey, keeps recent searches fast.
  • MCP endpoint — the mcp-searxng server, built into the image, running in HTTP mode. It forwards every agent query to the search engine over the internal network.

Nothing is exposed to the public internet except the ports you deliberately publish.


For anything beyond local testing, put the stack behind a reverse proxy that terminates TLS (HTTPS) for you. This is the recommended way to run it and the setup is the same regardless of which proxy you use (Caddy, Nginx, Traefik, HAProxy, …):

  • The proxy owns the TLS certificate (e.g. via Let's Encrypt) and does SSL offload — the containers themselves only speak plain HTTP on the internal/LAN interface.
  • You typically publish no or only local ports for the MCP endpoint and the search UI, and expose just one public HTTPS entry point (e.g. https://search.example.com).
  • Set SEARXNG_BASE_URL=https://search.example.com in .env so SearXNG builds correct result links behind the proxy.

Example with Caddy (it obtains and renews the certificate automatically):

search.example.com {
    reverse_proxy 127.0.0.1:8881   # SearXNG UI / API
}

# and, if your agents reach the MCP endpoint from outside the LAN:
mcp.example.com {
    reverse_proxy 127.0.0.1:8096   # MCP endpoint
}

Tip: if the proxy and this stack run on the same host, use 127.0.0.1 and keep the ports bound to localhost only (see "How it works" above) so they aren't reachable from the network directly.

Universal auth for any client: HTTP Basic Auth at the proxy

The built-in Bearer token only helps clients that can send a custom HTTP header (see Which agents …). If you use a client that can't (e.g. Claude Desktop), add HTTP Basic Auth at the reverse proxy instead: it runs on the plain HTTP transport, so it works with every MCP client, with no client-side configuration.

Example with Caddy (TLS + Basic Auth on the MCP endpoint):

# htpasswd -nb user 'a-long-password'  → use the result
mcp.example.com {
    basicauth {
        user $2a$14$............h
    }
    reverse_proxy 127.0.0.1:8096   # MCP endpoint
}

search.example.com {
    reverse_proxy 127.0.0.1:8881   # SearXNG UI / API (still TLS)
}

Combined approach: keep MCP_HTTP_HARDEN=false inside the stack and let the proxy be the single auth boundary. This is the most client-agnostic setup.

Security: whenever you expose the stack over a reverse proxy to the internet, enable authentication at the proxy (basicauth, IP allowlist) and — if your clients support it — MCP_HTTP_HARDEN=true too (defense in depth). See Hardening.


Deployment to a server / Portainer

docker compose up -d --build works anywhere Docker runs. This repo is also shaped as a GitOps stack so it deploys cleanly to Portainer: create a Git-based stack pointing at this repository, supply the environment variables via the stack's "Env" field, and Portainer builds and starts everything. Never commit secrets to Git.


License

This repository is MIT — see LICENSE.

Third-party components & their licenses

Component Source License Included text
SearXNG https://github.com/searxng/searxng AGPL-3.0 licenses/LICENSE-searxng-AGPL3
mcp-searxng https://github.com/ihor-sokoliuk/mcp-searxng (npm: mcp-searxng) MIT licenses/LICENSE-mcp-searxng-MIT

A note on AGPL-3.0 (please read)

SearXNG is licensed under the GNU Affero General Public License v3.0 — a copyleft license with a network-use clause. In short:

  • This repo's own code (compose file, Dockerfiles, docs) is MIT — free to use, modify and distribute, including commercially.
  • If you use the SearXNG container as-is, AGPL obligations are limited. If you modify SearXNG's own source and run it as a service others use over a network, you generally must make your modified source available under the AGPL. (Editing settings.yml is configuration, not source.)

This is not legal advice — see the full AGPL-3.0 text or consult a professional for your specific setup.