Which integrations are available for this server?

Provides tools for performing web searches through a SearXNG metasearch instance, with support for language, categories, time range, safe search, result limits, and health checks.

How do I use searxng-mcp-bridge?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@searxng-mcp-bridge search for recent articles about MCP servers" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

searxng-mcp-bridge

by bocklabs

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

SearXNG MCP Bridge Server

Release npm version License: MIT Node.js

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

Related MCP server: SearXNG MCP Server

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 @bocklabs/searxng-mcp-bridge

HTTP mode (for web/remote clients):

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

Via CLI flag (alternative to env var):

SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @bocklabs/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", "@bocklabs/searxng-mcp-bridge"],
      "env": {
        "SEARXNG_INSTANCE_URL": "http://localhost:8080"
      }
    }
  }
}

Cursor / VS Code (mcp_settings.json):

{
  "mcpServers": {
    "searxng-bridge": {
      "command": "npx",
      "args": ["-y", "@bocklabs/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 test             # Run tests
npm run test:coverage # Run tests and generate LCOV coverage
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

Fork the repository
Create a feature branch: git checkout -b feat/your-feature
Make your changes following existing code style
Ensure npm run test:coverage and npm run build pass
Open a pull request using the PR template

Bug reports and feature requests are welcome via GitHub Issues.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityActive

ResponsivenessUnresponsive

Resources

Need Help?

Related Servers

Related MCP Connectors

Serper A
io.github.pipeworx-io
Serper MCP — wraps the Serper Google Search API (serper.dev)
Search RAG Systems
2
LLMemoryOAuth
io.github.meir-may
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Search Knowledge & Memory
2
Keenable Web Search A
ai.keenable.api
Docs: https://docs.keenable.ai/mcp-server Keenable is a free, remote MCP server that gives agents access to the web index. Search the web with ranked results and date/site filters, then fetch any indexed page as clean markdown. Works out of the box with no account or API key.
Research & Data Search Web Scraping
23
Tavily A
io.github.pipeworx-io
Tavily MCP — wraps the Tavily API (tavily.com)
Search RAG Systems
2

Related MCP Servers

SearXNG Server
Search Browser Automation Web Scraping
ihor-sokoliuk
A
license
A
quality
A
maintenance
An MCP server implementation that integrates the SearxNG API, providing web search capabilities.
Updated 3 days ago (2026-09-18 01:44 UTC)
2
9,324 npm
1,246
MIT
SearXNG MCP Server
Search Browser Automation
martinchen448
A
license
A
quality
D
maintenance
Integrates with SearXNG metasearch engine to provide powerful web search capabilities across multiple search engines with filtering options for categories, languages, time ranges, and safe search levels. Enables comprehensive web searches, autocomplete suggestions, and search engine configuration access through MCP-compatible applications.
Updated a year ago (2025-10-28 02:55 UTC)
4
1
MIT
SearXNG MCP Server
Search Browser Automation
tobioffice
A
license
B
quality
D
maintenance
An MCP server that integrates with the SearXNG API to provide comprehensive web search capabilities with features like time filtering, language selection, and safe search. It also enables users to fetch and convert web content from specific URLs into markdown format.
Updated a year ago (2025-08-07 07:16 UTC)
2
6 npm
4
MIT
searxng-mcp-server
Search Browser Automation
roamer7038
A
license
Not graded
quality
D
maintenance
Enables privacy-focused web search via SearXNG for MCP clients, allowing users to perform searches with customizable parameters through natural language.
Updated 7 months ago (2026-02-27 21:14 UTC)
MIT