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
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a read-only diagnostic check, which is appropriate for a health check, but it does not explicitly state what is returned, whether it requires authentication, or whether it has side effects. For a zero-parameter tool this is acceptable, but more context would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It immediately conveys the tool's purpose and scope, and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, no output schema) the description is nearly complete. It states the health and connectivity check, which is sufficient for invocation. It could mention return values or typical use cases, but those are minor gaps for such a straightforward tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter semantics to document. Per the scoring rules, zero parameters default to a baseline of 4. The description does not need to compensate for missing schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: "Check the health and connectivity status of the SearxNG bridge." This clearly distinguishes it from the sibling tool "search," which performs searches rather than diagnostics. It could name the sibling explicitly, but the purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the diagnostic nature of the tool: an agent would call it to verify connectivity before or after using the SearxNG bridge. However, the description does not explicitly state when to use it, when not to, or mention the sibling search tool as an alternative. The guidance is adequate but relies on inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform a search using the configured SearxNG instance
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query string | |
| format | No | Result format (default: "json") | |
| language | No | Language code for search results (e.g., "en-US", "fr", "de") | |
| categories | No | Categories to search in (e.g., ["general", "images", "news"]) | |
| safesearch | No | Safe search level (0: off, 1: moderate, 2: strict) | |
| time_range | No | Time range for results | |
| max_results | No | Maximum number of results to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burdena and does essentially nothing with it. It does not say whether the call hits the network, how failures or unreachable instances surface, whether results are paginated or capped, or what the difference between json and html output actually means in practice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no filler, front-loading the action and the backend. It is appropriately sized, though the brevity reflects under-specification rather than disciplined editing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Seven parameters, no annotations, and no output schema, yet the description explains nothing about return shape, error modes, or the json-vs-html result formats that materially change what the agent receives. For a network-backed search tool with no other structured guidance, this leaves real gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear per-parameter descriptions and enums for format, time_range, and safesearch, so the structured data does the work. The description adds no additional semantics such as how categories combine or how max_results interacts with the backend's limits; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Perform a search") and reveals the backing engine (SearxNG), which tells the agent this is a web search rather than an internal data lookup. It does not differentiate from the only sibling, health_check, though the distinction is largely self-evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the tool name and the SearxNG reference; there are no explicit conditions for when to use or avoid it, no note on query phrasing, and no mention of when health_check should be called first. Acceptable only because the tool's purpose makes invocation fairly obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.12.18health_checksearchScored 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
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.