searxng-mcp

Token-efficient MCP server for SearXNG metasearch, for Claude Code and any MCP client that wants private web search and page extraction.

Connect your SearXNG instance to an LLM and get search, multi-query research, and readable page extraction as MCP tools. The server keeps model-visible output short and preserves full result payloads in hidden metadata, so you spend tokens on answers instead of raw HTML.

Install

As a Claude Code plugin:

/plugin marketplace add 88plug/claude-code-plugins
/plugin install searxng@88plug

Standalone, from any MCP client (no install step):

uvx --from git+https://github.com/88plug/searxng-mcp searxng-mcp

Related MCP server: SearXNG MCP Server

Quickstart

Run the server against a local SearXNG backend and confirm it is healthy:

export SEARXNG_MCP_BASE_URL=http://127.0.0.1:8890
uvx --from git+https://github.com/88plug/searxng-mcp searxng-mcp

In your MCP client, call the health tool. A healthy backend returns status ok: true with backend, cache, and render details. Then call search with a query and you get a compact ranked result list, with the full payload kept in _meta.

Rendered fetch is included in the default install. If the host has Chromium or Chrome, the server uses it; otherwise the first rendered fetch bootstraps Playwright Chromium into the user cache automatically.

What you get

• Compact model-visible output, with full details preserved in hidden _meta.

• Faster research through parallel search and fetch fan-out.

• Rendered extraction for JS-heavy pages, with no extra install flags.

• Self-hostable deployment for your own SearXNG-backed MCP server.

The server is thin by design. SearXNG does the search work; searxng-mcp handles tool shaping, caching, extraction, and transport.

MCP tools

Tools surface as mcp__searxng__search, mcp__searxng__fetch_url, and so on.

The server also exposes MCP resources and optional prompts:

• searxng://config — current settings, transport mode, and render support.

• searxng://guide — the available tools and when to use each.

• quick_lookup, deep_research, research_workflow — optional compatibility prompts for clients that support prompt surfaces.

Transports and deployment

The server supports stdio, streamable-http, and sse transports.

Local stdio for desktop clients and private workflows:

SEARXNG_MCP_TRANSPORT=stdio uvx --from git+https://github.com/88plug/searxng-mcp searxng-mcp

Streamable HTTP for a private service or team deployment:

uvx --from git+https://github.com/88plug/searxng-mcp searxng-mcp \
  --transport streamable-http --host 0.0.0.0 --port 8811

From a checkout (contributor path):

uv sync
uv run searxng-mcp

Docker

docker build -t searxng-mcp .
docker run --rm -p 8811:8811 --add-host=host.docker.internal:host-gateway \
  -e SEARXNG_MCP_BASE_URL=http://host.docker.internal:8890 \
  searxng-mcp

For a longer-running self-hosted service, use the hardened image and Compose stack:

docker build -f Dockerfile.prod -t searxng-mcp:prod .
cp docker-compose.env.example .env
docker compose up --build -d

Configuration

Set behavior through environment variables. The most common ones:

• SEARXNG_MCP_BASE_URL — SearXNG base URL. Default http://127.0.0.1:8890.

• SEARXNG_MCP_FALLBACK_BASE_URLS — comma-separated fallback SearXNG instances.

• SEARXNG_MCP_TRANSPORT — stdio, streamable-http, or sse.

• SEARXNG_MCP_SEARCH_TIMEOUT — backend search timeout, seconds.

• SEARXNG_MCP_FETCH_TIMEOUT — fetch timeout, seconds.

• SEARXNG_MCP_SEARCH_CACHE_TTL — search cache TTL, seconds.

• SEARXNG_MCP_FETCH_CACHE_TTL — fetch cache TTL, seconds.

• SEARXNG_MCP_FETCH_VERIFY_TLS — set to 0 to skip TLS verification on fetches.

• SEARXNG_MCP_CACHE_DIR — cache directory path.

• SEARXNG_MCP_RENDER_TIMEOUT — browser navigation timeout for rendered fetches.

• SEARXNG_MCP_RENDER_WAIT_MS — extra wait after DOM content load for rendered fetches.

• SEARXNG_MCP_RENDER_CONCURRENCY — concurrent rendered fetch limit.

• SEARXNG_MCP_RENDER_HEADLESS — set to 0 to show the browser.

• SEARXNG_MCP_RENDER_BROWSER_PATH — explicit Chromium or Chrome binary path.

• SEARXNG_MCP_RENDER_SANDBOX — set to 1 to keep Chromium sandboxing enabled.

• SEARXNG_MCP_RENDER_BLOCK_RESOURCES — set to 0 to allow images, fonts, stylesheets, and media during render.

• SEARXNG_MCP_RENDER_AUTO_FALLBACK — set to 0 to disable automatic rendered fallback.

• SEARXNG_MCP_RENDER_AUTO_MIN_WORDS — lower this to make auto-render more aggressive.

• SEARXNG_MCP_RENDER_AUTO_MIN_CHARS — lower this to make auto-render more aggressive.

Client configs

Use one of these command shapes with any MCP client:

• searxng-mcp — when the entry point is on PATH (after uv sync from a checkout, or pipx install).

• uvx --from git+https://github.com/88plug/searxng-mcp searxng-mcp — runs straight from this repo, no install step.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "searxng": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/88plug/searxng-mcp", "searxng-mcp"],
      "env": {
        "SEARXNG_MCP_BASE_URL": "http://127.0.0.1:8890",
        "SEARXNG_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

See client configs for Codex CLI, gemini-cli, and more.

Benchmarks

uv run searxng-mcp-bench --rounds 3

The benchmark reports raw backend latency, token-visible output size, merged multi-query search latency, research latency, fetch extraction latency, rendered fetch latency, and batch variants.

Documentation

• Getting started

• Deployment

• Security

• Tool reference

• Client configs

• Comparison

• Changelog

• SearXNG docs

Contributing

Contributions are welcome. See CONTRIBUTING.md and the code of conduct. To build and test from a checkout:

uv sync --all-groups
uv run pytest -q
uv run python -m compileall src
uv run mkdocs build --strict

License

Released under the Functional Source License, Version 1.1, ALv2 Future License (FSL-1.1-ALv2).

Free to use, copy, modify, and redistribute for any purpose except a Competing Use — offering this software (or a substantially similar substitute) as a commercial product or service. Each released version converts to the Apache License 2.0 on the second anniversary of its release date.

For commercial-use inquiries outside the Permitted Purpose: claude@cryptoandcoffee.com.