SearXNG MCP Bridge Server

An MCP (Model Context Protocol) server that bridges to a SearXNG metasearch engine instance. It exposes SearXNG search capabilities as MCP tools, allowing any MCP-compatible client (Claude Desktop, Cursor, opencode, etc.) to perform web searches through a self-hosted, privacy-respecting search engine.

Requirements

• Node.js >=25.0.0 <26
• A running SearXNG instance with JSON API enabled

Quick Start

1. Set up a SearXNG instance

docker run -d -p 8080:8080 --name searxng searxng/searxng

2. Run the MCP bridge

STDIO mode (default, for MCP clients like Claude Desktop):

npx -y @nitish-raj/searxng-mcp-bridge

HTTP mode (for web/remote clients):

TRANSPORT=http PORT=3002 SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @nitish-raj/searxng-mcp-bridge

Via CLI flag (alternative to env var):

SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @nitish-raj/searxng-mcp-bridge --transport=http

3. Configure your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "searxng-bridge": {
      "command": "npx",
      "args": ["-y", "@nitish-raj/searxng-mcp-bridge"],
      "env": {
        "SEARXNG_INSTANCE_URL": "http://localhost:8080"
      }
    }
  }
}

Cursor / VS Code (mcp_settings.json):

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

MCP Tools

search

Perform a web search using the configured SearXNG instance.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | Yes | The search query string | | language | string | No | Language code for results (e.g., en-US, fr, de) | | categories | string[] | No | Categories to search (e.g., ["general", "images", "news"]) | | time_range | string | No | Time range filter: day, week, month, year | | safesearch | number | No | Safe search level: 0 (off), 1 (moderate), 2 (strict) | | format | string | No | Result format: json (default) or html | | max_results | number | No | Maximum number of results to return |

Example response:

{
  "query": "test query",
  "number_of_results": 10,
  "results": [
    {
      "url": "https://example.com",
      "title": "Example Title",
      "content": "Snippet of the search result...",
      "engine": "google",
      "score": 1.0
    }
  ]
}

health_check

Check the health and connectivity status of the SearXNG instance and bridge server.

Parameters: None

Example response:

{
  "status": "healthy",
  "searxng_instance": "http://localhost:8080",
  "searxng_status": "healthy",
  "response_time_ms": 42,
  "cache_size": 3,
  "debug_mode": false,
  "version": "0.11.19",
  "timestamp": "2026-05-16T12:00:00.000Z"
}

Features

• Search Tool -- Perform web searches with configurable language, categories, time range, safe search, and result limits
• Health Check -- Monitor SearXNG connectivity, response time, cache size, and version
• Dual Transport -- Supports both STDIO (default) and HTTP streaming transports
• Response Caching -- 5-minute TTL cache with periodic cleanup to reduce duplicate requests
• Retry Logic -- Automatic retry with exponential backoff (3 attempts) for transient failures
• Startup Validation -- Validates SearXNG connection on launch with detailed error diagnostics
• Session Management -- HTTP transport includes UUID-based session tracking via mcp-session-id headers
• CORS Support -- Configurable origin whitelist with proper preflight handling
• Rate Limiting -- Built-in protection (100 requests/minute per IP) in HTTP mode
• Bearer Authentication -- Optional token-based auth for HTTP endpoints
• Debug Logging -- Redacted logs that strip sensitive info (tokens, session IDs, URLs)
• DNS Rebinding Protection -- Prevents DNS-based attacks in HTTP mode
• Graceful Shutdown -- Proper cleanup of transports and HTTP server on SIGINT/SIGTERM

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | SEARXNG_INSTANCE_URL | Yes | -- | Full URL of the SearXNG instance (e.g., http://localhost:8080) | | TRANSPORT | No | stdio | Transport protocol: stdio or http | | PORT | No | 3002 | HTTP server port (when TRANSPORT=http) | | HOST | No | 127.0.0.1 | Server bind address (use 0.0.0.0 for containers) | | CORS_ORIGIN | No | localhost:3002 (dev) / * (prod) | Comma-separated allowed origins for CORS | | MCP_HTTP_BEARER | No | -- | Bearer token for HTTP endpoint authentication | | SEARXNG_BRIDGE_DEBUG | No | false | Enable debug logging (true to enable) |

CLI Flags

| Flag | Description | |------|-------------| | --transport <stdio\|http> | Transport mode (overrides TRANSPORT env var) |

HTTP Transport

The HTTP transport implements the MCP Streamable HTTP specification (2025-03-26).

Endpoints:

| Method | Path | Description | |--------|------|-------------| | POST | /mcp | Send MCP JSON-RPC requests; initialize new sessions | | GET | /mcp | Server-Sent Events stream for notifications | | DELETE | /mcp | Terminate sessions | | OPTIONS | /mcp | CORS preflight requests | | GET | /healthz | Health check (returns { "status": "ok", "version": "..." }) |

Initialize and search via HTTP:

# 1. Initialize a session
curl -X POST http://localhost:3002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

# 2. List tools (use mcp-session-id from step 1 response)
curl -X POST http://localhost:3002/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <session-id>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# 3. Perform a search
curl -X POST http://localhost:3002/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <session-id>" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search","arguments":{"query":"hello world"}}}'

Docker

The Dockerfile is based on node:25-alpine and exposes port 8081.

# Build
docker build -t searxng-mcp-bridge .

# Run in STDIO mode (default)
docker run -d \
  -e SEARXNG_INSTANCE_URL=http://host.docker.internal:8080 \
  searxng-mcp-bridge

# Run in HTTP mode
docker run -d -p 8081:8081 \
  -e TRANSPORT=http \
  -e PORT=8081 \
  -e HOST=0.0.0.0 \
  -e SEARXNG_INSTANCE_URL=http://host.docker.internal:8080 \
  searxng-mcp-bridge

Note: Use HOST=0.0.0.0 when running inside containers to allow external connections.

Development

npm install          # Install dependencies
npm run dev          # Run with tsx (TypeScript execution, no build step)
npm run build        # Compile TypeScript to JavaScript
npm run watch        # Watch for changes and rebuild automatically
npm run start        # Run the compiled server (stdio mode)
npm run start:http   # Run the compiled server (HTTP mode on port 3002)
npm run inspector    # Run MCP inspector for interactive testing

Release scripts:

npm run release:patch   # Bump patch version (0.11.x)
npm run release:minor   # Bump minor version (0.x.0)
npm run release:major   # Bump major version (x.0.0)

Releases are automated via release-please with Renovate for dependency management.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Make your changes following existing code style
4. Ensure npm run build passes
5. Open a pull request using the PR template

Bug reports and feature requests are welcome via GitHub Issues.

License

MIT -- Copyright (c) 2025 Nitish Raj