SearXNG MCP Bridge Server

This is a Model Context Protocol (MCP) server that acts as a bridge to a SearXNG instance. It allows compatible clients to perform searches using a configured SearXNG instance via MCP tools.

Quick Start (Using from npm)

Set up a SearXNG instance:

# Using Docker
docker run -d -p 8888:8080 --name searxng searxng/searxng

Install and run the MCP bridge

Default (STDIO, unchanged):

# Run directly with npx (default - stdio transport)
npx -y @nitish-raj/searxng-mcp-bridge

Optional: Run as an HTTP server (new, opt-in)

 # Using env variables (recommended)
  TRANSPORT=http PORT=3002 HOST=127.0.0.1 SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @nitish-raj/searxng-mcp-bridge



# Or run the built bundle
TRANSPORT=http node build/index.js

Configure in your MCP settings file (stdio / legacy clients) Add to your 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": "http://localhost:8080"
       },
      "disabled": false
    }
  }
}

HTTP Configuration: Set TRANSPORT=http to run the bridge over HTTP instead of stdio. The transport mode can be configured via environment variables.

Features

Search Tool: Perform web searches using SearXNG with configurable parameters
Health Check: Monitor SearXNG instance connectivity and performance
Dual Transport: Supports both STDIO (default) and HTTP transports
Session Management: HTTP transport includes session-based connections
CORS Support: Proper cross-origin headers for web client integration
Rate Limiting: Built-in protection against excessive requests (HTTP mode)

Configuration

SEARXNG_INSTANCE_URL — REQUIRED. The full URL of the SearXNG instance (e.g., http://localhost:8080).
TRANSPORT — Transport protocol: stdio (default) or http
PORT — HTTP server port. Default: 3000 (use 3002 for development)
HOST — Server bind address. Default: 127.0.0.1 (use 0.0.0.0 for containers)
CORS_ORIGIN — Comma-separated list of allowed origins for CORS. Default: localhost:3002 (development) or * (production)
MCP_HTTP_BEARER — Optional bearer token for HTTP authentication HTTP Transport Features:
Session management with mcp-session-id headers
Secure CORS with origin whitelist validation
Rate limiting (100 requests/minute per IP)
Optional bearer authentication via MCP_HTTP_BEARER
DNS rebinding protection

Security Notes:

CORS uses secure whitelist in development (localhost:3002 only)
Production reflects specific origins for credentialed requests (CORS-compliant)
Set CORS_ORIGIN to customize allowed origins for your use case
Set TRANSPORT=stdio to revert to stdio mode

HTTP Transport

The HTTP transport implements the MCP Streamable HTTP specification (2025-03-26) with the following endpoints:

MCP Endpoints:

POST /mcp - Send MCP requests
GET /mcp - Server-Sent Events for notifications
DELETE /mcp - Terminate sessions
OPTIONS /mcp - CORS preflight requests

System Endpoints:

GET /healthz - Health check and status

Test HTTP endpoint:

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

This returns a JSON-RPC response with the list of available tools (search and health_check).

Docker

The Dockerfile exposes port 8081 for HTTP transport. To run the container and allow HTTP access:

# Build (example)
docker build -t searxng-mcp-bridge .

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

# To run HTTP transport inside 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 containerized set HOST=0.0.0.0 or rely on the default exposed port mapping.

Usage

STDIO Clients: Use the tool unchanged - no configuration changes required.

HTTP Clients: Connect to http://localhost:3002/mcp (development port) and send MCP JSON-RPC requests.

Development

npm install: Install dependencies.
npm run build: Compile TypeScript to JavaScript.
npm run watch: Watch for changes and rebuild automatically.
npm run inspector: Run the MCP inspector to test the server.
npm run start:http: Start server in HTTP streaming mode on localhost:3002.

Migration & Compatibility

Backward Compatibility:

STDIO remains the default transport - existing users need no changes
All tool names, parameters, and responses remain unchanged
Configuration is opt-in via environment variables

Migration to HTTP:

Set TRANSPORT=http to enable HTTP transport
Configure PORT and HOST as needed
Update client to use HTTP endpoint instead of stdio

Rollback:

Set TRANSPORT=stdio or omit the variable to return to stdio