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.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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.
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.
Node.js >=25.0.0 <26
A running SearXNG instance with JSON API enabled
Related MCP server: searxng-mcp-server
docker run -d -p 8080:8080 --name searxng searxng/searxngSTDIO mode (default, for MCP clients like Claude Desktop):
npx -y @bocklabs/searxng-mcp-bridgeHTTP mode (for web/remote clients):
TRANSPORT=http PORT=3002 SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @bocklabs/searxng-mcp-bridgeVia CLI flag (alternative to env var):
SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @bocklabs/searxng-mcp-bridge --transport=httpClaude 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
}
}
}searchPerform a web search using the configured SearXNG instance.
Parameters:
Parameter | Type | Required | Description |
| string | Yes | The search query string |
| string | No | Language code for results (e.g., |
| string[] | No | Categories to search (e.g., |
| string | No | Time range filter: |
| number | No | Safe search level: |
| string | No | Result format: |
| 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_checkCheck 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"
}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
Variable | Required | Default | Description |
| Yes | -- | Full URL of the SearXNG instance (e.g., |
| No |
| Transport protocol: |
| No |
| HTTP server port (when |
| No |
| Server bind address (use |
| No |
| Comma-separated allowed origins for CORS |
| No | -- | Bearer token for HTTP endpoint authentication |
| No |
| Enable debug logging ( |
Flag | Description |
| Transport mode (overrides |
The HTTP transport implements the MCP Streamable HTTP specification (2025-03-26).
Endpoints:
Method | Path | Description |
|
| Send MCP JSON-RPC requests; initialize new sessions |
|
| Server-Sent Events stream for notifications |
|
| Terminate sessions |
|
| CORS preflight requests |
|
| Health check (returns |
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"}}}'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-bridgeNote: Use
HOST=0.0.0.0when running inside containers to allow external connections.
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 testingRelease 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.
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.
Check the health and connectivity status of the SearxNG bridge
Inputs: no named parameters.
Perform a search using the configured SearxNG instance
Inputs: query (required), format, language, categories, +3 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 2 tools
search and health_check have clearly distinct purposes: one performs searches, the other reports connectivity/health. There is no realistic overlap that would cause an agent to misselect between them.
Both names use snake_case, which is consistent. However, search is a bare verb while health_check is a verb/noun-style check name, so the pattern is mostly but not perfectly consistent.
Two tools is slightly thin in general, but the server is narrowly scoped as a SearxNG bridge. search and health_check both earn their place and cover the essential surface without bloat.
The core lifecycle for this bridge is covered: perform a search and verify health/connectivity. Minor optional gaps might include exposing advanced search parameters or instance/engine metadata, but nothing essential is missing.
Serper MCP — wraps the Serper Google Search API (serper.dev)
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Web search API and MCP server for developers building AI agents.
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.