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)

1. Set up a SearXNG instance: bash # Using Docker docker run -d -p 8888:8080 --name searxng searxng/searxng

2. Install and run the MCP bridge

Default (STDIO, unchanged): bash # Run directly with npx (default - stdio transport) npx -y @nitish-raj/searxng-mcp-bridge

Optional: Run as an HTTP server (new, opt-in) ```bash # 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 use the CLI flag form npx -y @nitish-raj/searxng-mcp-bridge --transport=http

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

1. Configure in your MCP settings file (stdio / legacy clients) Add to your MCP settings file (e.g., ~/.vscode-server/.../mcp_settings.json): json { "mcpServers": { "searxng-bridge": { "command": "npx", "args": [ "-y", "@nitish-raj/searxng-mcp-bridge" ], "env": { "SEARXNG_INSTANCE_URL": "YOUR_SEARXNG_INSTANCE_URL" }, "disabled": false } } }

Smithery Configuration: When using Smithery, you can set transport: "http" in the Smithery config to run the bridge over HTTP instead of stdio. Smithery will set TRANSPORT in the process environment when launching the bridge.

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, Smithery uses 8081)
• 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 for Smithery)
• 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).

Using Smithery

Smithery provides container deployment with automatic HTTP transport configuration. Install via Smithery:

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

Smithery automatically handles: - Container deployment with HTTP transport - Port configuration (uses 8081 by default) - Environment variable management - Secure CORS configuration for web clients

Docker

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

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

# Run mapping port 8081 (Smithery default)
 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. Port 8081 is used for Smithery deployment compatibility.

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.

Smithery: Smithery handles all configuration automatically.

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.

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