SearXNG Bridge
About
A bridge server for connecting to a SearXNG metasearch engine instance.
Details
- Author
- nitish-raj
- Categories
- Search, Other, API
Jump to
Setup
Install SearXNG Bridge in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/nitish-raj/searxng-mcp-bridge
Follow the installation instructions in the repository README, then restart your MCP client.
AnMCP (Model Context Protocol)server that bridges to aSearXNGmetasearch 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 runningSearXNGinstance with JSON API enabled
docker run -d -p 8080:8080 --name searxng searxng/searxng
STDIO mode(default, for MCP clients like Claude Desktop):
TRANSPORT=http PORT=3002 SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @nitish-raj/searxng-mcp-bridge
SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @nitish-raj/searxng-mcp-bridge --transport=http
Claude Desktop(~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS,%APPDATA%\Claude\claude_desktop_config.jsonon Windows):
{ "mcpServers": { "searxng-bridge": { "command": "npx", "args": ["-y", "@nitish-raj/searxng-mcp-bridge"], "env": { "SEARXNG_INSTANCE_URL": "http://localhost:8080" } } } }
{ "mcpServers": { "searxng-bridge": { "command": "npx", "args": ["-y", "@nitish-raj/searxng-mcp-bridge"], "env": { "SEARXNG_INSTANCE_URL": "http://localhost:8080" }, "disabled": false } } }
Perform a web search using the configured SearXNG instance.
{ "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 } ] }
Check the health and connectivity status of the SearXNG instance and bridge server.
{ "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 viamcp-session-idheaders
- 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
The HTTP transport implements theMCP Streamable HTTP specification(2025-03-26).
# 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 onnode:25-alpineand exposes port8081.
# 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:UseHOST=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 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
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 viarelease-pleasewith Renovate for dependency management.
- Fork the repository
- Create a feature branch:git checkout -b feat/your-feature
- Make your changes following existing code style
- Ensurenpm run buildpasses
- Open a pull request using thePR template
Bug reports and feature requests are welcome viaGitHub Issues.
Search global news using natural language. Webz.io News Search API returns the most relevant articles and content, with filters for source, country, language, date, sentiment, and category.
Search the web using Kagi's search API
Multi-provider search broker for AI agents. Routes across SearXNG, Brave, Serper, Tavily, and Exa with automatic fallback, RRF ranking, content extraction, and budget enforcement.
A search server for the Model Context Protocol (MCP) that uses the Baidu Wenxin API.
Perform web, news, and image searches using the Microsoft Bing Search API.
An MCP server for web and local search using the Brave Search API.
Integrates the Brave Search API for both web and local search capabilities. Requires a BRAVE_API_KEY.
An MCP server for the Brave Search API, providing web and local search capabilities via a streaming SSE interface.
An MCP server for the Brave Search API, providing both web and local search capabilities.
Search for cocktail recipes using the cezzis.com API.
Free search API for AI agents — 105 engines, 22 profiles, 94.3% SimpleQA accuracy, MCP server with 5 tools
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
