SearXNG MCP Server for Claude Code: Setup & Config

What you can do with SearXNG in Claude Code

A self-managed SearXNG bridge that adds content reading, backend discovery, and replica handling.

• Add filtered web research to an assistant using an existing SearXNG deployment.
• Use interchangeable SearXNG replicas for failover.

Before you start: SearXNG in Claude Code

• Node.js and npx
• An accessible SearXNG instance, preferably with JSON search enabled
• An MCP-compatible client

The README's quick start uses npx. Docker and global-package alternatives are documented. MCP_HTTP_PORT enables HTTP mode. SEARXNG_HTML_FALLBACK is an optional compatibility measure when JSON responses are unavailable.

SearXNG Claude Code configuration

1. Choose Claude Code configuration scope

   For SearXNG MCP Server, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add SearXNG MCP Server to Claude Code

   Use the mcp-searxng entry below in mcpServers. Keep SearXNG MCP Server's documented stdio connection fields and your other Claude Code entries.

3. Check SearXNG MCP Server in Claude Code

   SearXNG MCP Server: Inspect claude mcp list and /mcp status.

{
  "mcpServers": {
    "mcp-searxng": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-searxng"
      ],
      "env": {
        "SEARXNG_URL": "<SearXNG instance URL or semicolon-separated interchangeable replica URLs>"
      }
    }
  }
}

claude mcp add-json --scope project 'mcp-searxng' '{"type":"stdio","command":"npx","args":["-y","mcp-searxng"],"env":{"SEARXNG_URL":"<SearXNG instance URL or semicolon-separated interchangeable replica URLs>"}}'

SearXNG tools available to Claude Code

SearXNG's stored tool list documents 4 tools; compare it with Claude Code's connected tool list, because the stored list is not a live check.

searxng_web_search

For SearXNG's searxng_web_search, review the permission request and arguments in Claude Code before approval.

Search SearXNG with pagination, filters, and text or JSON responses.

searxng_search_suggestions

For SearXNG's searxng_search_suggestions, review the permission request and arguments in Claude Code before approval.

searxng_instance_info

For SearXNG's searxng_instance_info, review the permission request and arguments in Claude Code before approval.

web_url_read

For SearXNG's web_url_read, review the permission request and arguments in Claude Code before approval.

Read supported URL content with section, paragraph, heading, and character-range controls.

SearXNG: full stored tool descriptions

Troubleshooting SearXNG in Claude Code

• If SearXNG MCP Server fails to start, check npx mcp-searxng (Node.js/npm), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• SearXNG MCP Server: check SEARXNG_URL; keep credentials out of shared .mcp.json.
• SearXNG MCP Server uses stdio here: Claude Code must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires an accessible SearXNG instance.
• Known limitation: HTML fallback is best-effort and loses relevance scores and engine metadata.
• Known limitation: The URL reader rejects PDFs and other binary downloads.
• General Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions