- Go 96.7%
- Dockerfile 3.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
- 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 |
||
| auth-gateway | ||
| docs | ||
| licenses | ||
| mcp | ||
| searxng | ||
| .env.example | ||
| .gitignore | ||
| docker-compose.auth.yml | ||
| docker-compose.yml | ||
| LICENSE | ||
| README.md | ||
| settings.yml | ||
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
Authorizationheader / 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.mdand enable it with:docker compose -f docker-compose.yml -f docker-compose.auth.yml --profile auth up -d --buildThe
authoverride also removesmcp-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 |
Hardening (optional, but recommended)
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:
MCP_HTTP_HARDEN=truerequiresMCP_AUTH_TOKENandMCP_ALLOWED_ORIGINS. If they're missing the MCP container won't start — see Troubleshooting.MCP_ALLOWED_HOSTSmust contain the exact host name (with port) your agent sends as theHost:header. A wildcard does not work here. If it's missing, requests fail withInvalid 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-searxngserver, 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.
Recommended: run behind a reverse proxy with TLS
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.comin.envso 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.1and 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=falseinside 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=truetoo (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.ymlis configuration, not source.)
This is not legal advice — see the full AGPL-3.0 text or consult a professional for your specific setup.