searxng-mcp

SearXNG search MCP for Claude Code and Grok — privacy-respecting web search and page extraction for AI agents and any MCP client.

searxng-mcp is a token-efficient Model Context Protocol (MCP) server that connects your self-hosted SearXNG metasearch instance to Claude Code, Anthropic-compatible clients, and other LLM / AI-agent tooling. You get privacy-respecting web search across 70+ engines plus readable page extraction — without shipping raw HTML into the model context.

Search, multi-query research, and fetch tools keep model-visible output short. Full result payloads stay in hidden _meta, so tokens go to answers. Deploy via stdio for local Claude workflows, or streamable-http / Docker for a self-hosted MCP service with optional Playwright rendered fetch for JS-heavy pages.

Install

Claude Code plugin (hub-first):

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

Grok Build

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

Standalone MCP server — any client, no install step:

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

Related MCP server: SearXNG MCP Bridge

Quickstart

Point the server at 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 health. A healthy backend returns ok: true with backend, cache, and render details. Then call search — you get a compact ranked list; the full payload stays in _meta.

Rendered fetch ships 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.

Features

MCP tools

Tools surface as mcp__searxng__search, mcp__searxng__fetch_url, and so on.

Resources and optional prompts:

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

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

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

Transports and deployment

Supports stdio, streamable-http, and sse.

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

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

Hardened image and Compose for a longer-running self-hosted service:

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

Configuration

Common environment variables:

• 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

• 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

• SEARXNG_MCP_RENDER_AUTO_FALLBACK — set to 0 to disable automatic rendered fallback

• SEARXNG_MCP_RENDER_AUTO_MIN_WORDS — lower to make auto-render more aggressive

• SEARXNG_MCP_RENDER_AUTO_MIN_CHARS — lower to make auto-render more aggressive

Client configs

Use either command shape 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 from this repo with 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

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

Full site: 88plug.github.io/searxng-mcp

• Getting started

• Installation

• Configuration

• Deployment

• Security

• Tool reference

• Client configs

• Comparison

• Changelog

• SearXNG docs

Development

From a checkout:

uv sync
uv run searxng-mcp

Build and test:

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

Contributions welcome. See CONTRIBUTING.md and the code of conduct.

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: andrew@88plug.com.