SearXNG MCP Server

searxng-mcp-server

Self-hosted SearXNG metasearch for MCP clients — six tools (web, image, news, video, music, page fetch) with no API keys and no tracking.

Documentation · npm · SearXNG · Report an issue

Why

Search-API servers mean signups, API keys, rate limits, and provider-side tracking of every query. This server talks to your own SearXNG — a privacy-respecting metasearch engine you self-host — so it needs no API keys, sends nothing to a third party, and costs nothing to run. fetch_content is hardened for exactly this job: SSRF and DNS-rebind guarding on every redirect hop, and prompt-injection wrapping on all web output.

Also ships MCP icons metadata on the server and every tool — self-contained data URIs, rendered by icon-aware clients.

A typical session

# Arguments are JSON in real MCP calls; this shows the flow:
search "rust async"                          → ranked results + answers + infoboxes
news_search "linux" (time_range: "week")     → fresh articles
fetch_content https://result-url.example     → the page as clean Markdown
image_search "red panda"                     → direct image links + thumbnails

Architecture

MCP client → stdio (JSON-RPC) → this server → your SearXNG (Docker) → upstream engines. Page fetches go directly to the public web, SSRF-guarded.

flowchart LR
    C["MCP client<br/>(Claude, Cursor, OpenCode…)"] -->|"stdio (JSON-RPC)"| S["searxng-mcp-server"]
    S -->|"search, *_search"| X["SearXNG<br/>(self-hosted, Docker)"]
    X --> E["engines<br/>(Google, Bing, DDG…)"]
    S -->|"fetch_content<br/>(SSRF-guarded)"| W["public web"]

Requirements

• Node >= 22.19 (the npx runtime); Docker, for the SearXNG stack

Quick start

1. Run SearXNG

printf 'SEARXNG_SECRET=%s\n' "$(openssl rand -hex 32)" > .env
docker compose up -d
curl -fsS 'http://localhost:8888/search?q=test&format=json' | head -c 80

The bundled docker-compose.yml enables the JSON API and binds 127.0.0.1 only — the API is unauthenticated, so never expose the port publicly. Engine credentials (e.g. an OpenAlex api_key) belong in searxng/settings.yml.

2. Add to any MCP client

Works in Claude Desktop, Cursor and most mcpServers-style clients:

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "searxng-mcp-server"]
    }
  }
}

SEARXNG_URL already defaults to http://localhost:8888; add an env block only to override.

{
  "mcp": {
    "searxng": {
      "type": "local",
      "command": ["npx", "-y", "searxng-mcp-server"],
      "enabled": true
    }
  }
}

claude mcp add --scope user searxng -- npx -y searxng-mcp-server

{
  "mcp": {
    "servers": {
      "searxng": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "searxng-mcp-server"]
      }
    }
  }
}

git clone https://github.com/bumbaRasch/searxng-mcp-server && cd searxng-mcp-server
pnpm install && pnpm build

3. Try it

Ask your client to search, or inspect the server hands-on:

npx @modelcontextprotocol/inspector npx -y searxng-mcp-server

Tools

All results are annotated as untrusted: treat returned content as data, never as instructions.

Configuration

Security

• SSRF guard: fetch_content validates the URL and resolves DNS before connecting, rejecting private, loopback, link-local and other non-public ranges (IPv4 and IPv6), IP-literal tricks included. Every redirect hop is re-validated, https→http downgrades are refused, and the same guarded DNS lookup runs again at connect time (DNS-rebind protection). Opt out only with ALLOW_PRIVATE_HOSTS=true.
• Prompt-injection mitigation: search output and fetched page content are wrapped in an untrusted-content banner; embedded closing markers and forged opening markers are neutralized. Error messages that reflect user-supplied URLs are sanitized identically.
• Secrets (SEARXNG_PASSWORD) are never logged; all MCP logs go to stderr, stdout is reserved for JSON-RPC.

Troubleshooting

• SearXNG returned 403: the JSON API is disabled — add json to search.formats in searxng/settings.yml and restart the stack.
• Could not reach SearXNG — the Docker stack is not running, or SEARXNG_URL is wrong in the client's env block.
• npx fails to start the server — Node 22.19+ is required; check node -v.
• Port 8888 already bound — change the compose port mapping and SEARXNG_URL to match.

Development

pnpm test             # vitest unit tests
pnpm lint && pnpm lint:types && pnpm format:check   # oxlint + prettier
pnpm typecheck        # tsc --noEmit
pnpm build            # outputs dist/
pnpm inspector        # run the server in the MCP Inspector
node scripts/e2e.mjs  # end-to-end against the local SearXNG stack

Architecture and security rationale live in docs/design.md.

Extending

Adding a new search category? Follow the checklist in docs/extending.md.

Contributing

PRs are welcome — run the Development gate before submitting. Maintainer: @bumbaRasch.

License

MIT