SearXNG MCP Server for Windsurf: Setup & Config

What you can do with SearXNG in Windsurf

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

• Read selected sections or headings from a result URL.
• Use interchangeable SearXNG replicas for failover.

Before you start: SearXNG in Windsurf

• 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 Windsurf configuration

1. Choose Windsurf configuration scope

   For SearXNG MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add SearXNG MCP Server to Windsurf

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

3. Check SearXNG MCP Server in Windsurf

   SearXNG MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

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

SearXNG tools available to Windsurf

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

searxng_web_search

After refreshing SearXNG in Windsurf settings, check Cascade's tool list for searxng_web_search.

searxng_search_suggestions

After refreshing SearXNG in Windsurf settings, check Cascade's tool list for searxng_search_suggestions.

Request autocomplete suggestions for a partial or complete query.

searxng_instance_info

After refreshing SearXNG in Windsurf settings, check Cascade's tool list for searxng_instance_info.

web_url_read

After refreshing SearXNG in Windsurf settings, check Cascade's tool list for web_url_read.

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

SearXNG: full stored tool descriptions

Troubleshooting SearXNG in Windsurf

• Check npx mcp-searxng (Node.js/npm) on the machine running Windsurf's MCP integration for SearXNG MCP Server; refresh MCP and inspect Cascade's tools.
• Check SEARXNG_URL for SearXNG MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• SearXNG MCP Server uses stdio here: Windsurf 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 Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions