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

[!NOTE] You need a reachable SearXNG instance. Default base URL is http://127.0.0.1:8890. Override with SEARXNG_MCP_BASE_URL.

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

[!TIP] If you expose the HTTP transport, treat it like an internal service. fetch_url and fetch_many can request client-supplied URLs, so put streamable-http behind auth or a reverse proxy. Apply the same controls you would for any SSRF-capable tool. SEARXNG_MCP_FETCH_VERIFY_TLS=0 is only for private or self-signed backends.

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

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.