SearXNG MCP Bridge Server

This software functions as an MCP intermediary, proxying search operations directed at a configured SearXNG endpoint. It enables AI clients supporting the MCP specification to leverage decentralized search capabilities.

Rapid Deployment Guide (via npm)

Establish a SearXNG Endpoint: bash # Utilizing Docker for instance setup docker run -d -p 8888:8080 --name searxng searxng/searxng
Install and Initiate the MCP Service

Default transport (STDIO): bash # Direct execution using npx (default stdio transport) npx -y @nitish-raj/searxng-mcp-bridge

Alternative: Operating as an HTTP listener (new, user-enabled) bash # Configuration via environment variables (preferred) TRANSPORT=http PORT=3002 HOST=127.0.0.1 SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @nitish-raj/searxng-mcp-bridge

# Or utilizing command-line arguments npx -y @nitish-raj/searxng-mcp-bridge --transport=http

# Or executing the compiled bundle directly TRANSPORT=http node build/index.js

Integrate into MCP Configuration (For stdio clients) In your primary MCP settings file (e.g., ~/.vscode-server/.../mcp_settings.json):

{ "mcpServers": { "searxng-bridge": { "command": "npx", "args": [ "-y", "@nitish-raj/searxng-mcp-bridge" ], "env": { "SEARXNG_INSTANCE_URL": "YOUR_SEARXNG_INSTANCE_URL" }, "disabled": false } } }

Smithery Integration Note: If leveraging Smithery, setting transport: "http" within the Smithery configuration directs the launch process to use HTTP communication rather than standard I/O.

Core Capabilities

Information Retrieval Tool: Executes web searches via SearXNG, supporting various parameters.
Liveness Probe: Checks the connection status and operational health of the target SearXNG service.
Dual Channel Support: Native compatibility with both STDIO and network (HTTP) communication.
Session Handling: HTTP mode incorporates mechanisms for connection persistence via session identifiers.
Web Client Safety: Implements necessary Cross-Origin Resource Sharing (CORS) headers.
Traffic Throttling: Includes safeguards against request flooding when operating in HTTP mode.

Operational Parameters

SEARXNG_INSTANCE_URL — MANDATORY. The complete URI to the operational SearXNG installation (e.g., http://localhost:8080).
TRANSPORT — Specifies the communication layer: stdio (default) or http.
PORT — The port for the HTTP listener. Default is 3000 (use 3002 for typical dev, Smithery defaults to 8081).
HOST — The network interface address to bind to. Default: 127.0.0.1 (use 0.0.0.0 for containerized environments).
CORS_ORIGIN — A comma-delimited list of accepted host origins. Defaulting to localhost:3002 (dev) or * (production/Smithery).
MCP_HTTP_BEARER — Optional secret token required for HTTP authentication.

HTTP Transport Enhancements: - State management utilizing mcp-session-id headers. - Strict validation of allowed origins for CORS compliance. - A maximum throughput limit (100 requests per minute per source IP). - Optional API key validation via MCP_HTTP_BEARER. - Defense mechanisms against DNS rebinding attacks.

Security Considerations: - Development CORS restricts access solely to localhost:3002. - Production deployments enforce explicit origin whitelists for credentialed interactions. - Customize allowed access points via CORS_ORIGIN. - Revert to legacy behavior by setting TRANSPORT=stdio.

HTTP Transport Interface

This component adheres to the MCP Streamable HTTP specification (dated 2025-03-26), exposing the following interfaces:

MCP Channels: - POST /mcp - For transmitting structured MCP commands. - GET /mcp - Leverages Server-Sent Events (SSE) for asynchronous updates. - DELETE /mcp - Used to gracefully end established sessions. - OPTIONS /mcp - Handles preflight CORS checks.

System Interface: - GET /healthz - Reports operational status.

Client Testing Endpoint Example: bash curl -X POST http://localhost:3002/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

This execution yields a JSON-RPC reply enumerating available methods (search and health_check).

Utilization via Smithery

Smithery facilitates automated deployment, pre-configuring the bridge for HTTP transport.

bash npx -y @smithery/cli install @nitish-raj/searxng-mcp-bridge --client claude

Smithery manages: - Deployment within a containerized environment using HTTP. - Port assignment (defaulting to 8081). - Environment variable setup. - Secure configuration for web-based clients.

Docker Deployment

The included Dockerfile exposes port 8081 to align with Smithery standards (HTTP transport). bash

Compilation example

docker build -t searxng-mcp-bridge .

Execution mapping port 8081 (Smithery standard)

docker run -d -p 8081:8081 --env SEARXNG_INSTANCE_URL=http://localhost:8080 --name searxng-mcp-bridge searxng-mcp-bridge

Execution enforcing HTTP transport within the container:

docker run -d -p 8081:8081 -e TRANSPORT=http -e PORT=8081 -e SEARXNG_INSTANCE_URL=http://localhost:8080 searxng-mcp-bridge

Note: When running inside a container, ensure HOST=0.0.0.0 or rely on external port mapping. Port 8081 is reserved for Smithery integration.

Usage Paradigms

Clients using STDIO: No alteration to existing setups is required.

Clients using HTTP: Interface with http://localhost:3002/mcp (development path) by submitting MCP JSON-RPC payloads.

Smithery Users: All networking configuration is abstracted away.

Maintenance Workflow

npm install: Fetches required dependencies.
npm run build: Compiles source code from TypeScript to JavaScript.
npm run watch: Runs a continuous compilation process upon file changes.
npm run inspector: Launches the MCP server introspection utility for testing.

Evolution & Compatibility

Backward Stability: - STDIO remains the default transport mechanism; prior configurations are unaffected. - All established tool names, arguments, and output structures are preserved. - Configuration shifts are entirely opt-in via environment variables.

Transitioning to HTTP: - Activate HTTP by setting TRANSPORT=http. - Adjust PORT and HOST as dictated by the deployment environment. - Update client logic to target the HTTP interface address.

Reversion Procedure: - Set TRANSPORT=stdio or omit the variable entirely to revert to the standard I/O channel.