# Mcp Searxng > Private web search for AI assistants via SearXNG โ€” supports Claude, Cursor, and any MCP client - **Type:** MCP server - **Install:** `agentstack add mcp-ihor-sokoliuk-mcp-searxng` - **Verified:** Yes โ€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [ihor-sokoliuk](https://agentstack.voostack.com/s/ihor-sokoliuk) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [ihor-sokoliuk](https://github.com/ihor-sokoliuk) - **Source:** https://github.com/ihor-sokoliuk/mcp-searxng - **Website:** https://www.npmjs.com/package/mcp-searxng ## Install ```sh agentstack add mcp-ihor-sokoliuk-mcp-searxng ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # ๐Ÿ” SearXNG MCP Server **Private web search for AI assistants โ€” connect any SearXNG instance to Claude, Cursor, and more.** [](https://github.com/ihor-sokoliuk/mcp-searxng/stargazers) [](https://www.npmjs.com/package/mcp-searxng) [](https://www.npmjs.com/package/mcp-searxng) [](https://hub.docker.com/r/isokoliuk/mcp-searxng) [](LICENSE) [](https://scorecard.dev/viewer/?uri=github.com/ihor-sokoliuk/mcp-searxng) [](https://www.bestpractices.dev/projects/13143) [](https://glama.ai/mcp/servers/ihor-sokoliuk/mcp-searxng) [](https://github.com/mcp/ihor-sokoliuk/mcp-searxng) An [MCP server](https://modelcontextprotocol.io/introduction) that integrates the [SearXNG](https://docs.searxng.org) API, giving AI assistants web search capabilities. โœจ Featured in the [GitHub MCP Registry](https://github.com/mcp/ihor-sokoliuk/mcp-searxng). ## Quick Start Add to your MCP client configuration (e.g. `claude_desktop_config.json`): ```json { "mcpServers": { "searxng": { "command": "npx", "args": ["-y", "mcp-searxng"], "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL" } } } } ``` Replace `YOUR_SEARXNG_INSTANCE_URL` with the URL of your SearXNG instance (e.g. `https://searxng.example.com`). You can also provide interchangeable replicas as a semicolon-separated list, e.g. `https://one.example.com;https://two.example.com`. ## Features - **Web Search**: General queries, news, articles, with pagination. - **Instance Failover**: Configure multiple interchangeable SearXNG replicas in `SEARXNG_URL`; searches fail over by default and can optionally fan out in parallel. - **Structured Search Output**: Choose formatted text or raw SearXNG-shaped JSON with `response_format`. - **Direct Answers & Metadata**: Text results surface SearXNG answers, corrections, suggestions, and infoboxes before result lists. - **Search Suggestions**: Query autocomplete via SearXNG's `/autocompleter` endpoint. - **Instance Capability Discovery**: Inspect configured categories, engines, defaults, locales, and plugins from `/config`. - **URL Content Reading**: Advanced content extraction with pagination, section filtering, and heading extraction. - **Intelligent Caching**: URL content is cached with TTL (Time-To-Live) to improve performance and reduce redundant requests. - **Pagination**: Control which page of results to retrieve. - **Time Filtering**: Filter results by time range (day, week, month, year). - **Language Selection**: Filter results by preferred language. - **Safe Search**: Control content filtering level for search results. - **Relevance Filtering**: Filter out low-scoring search results with `min_score`. ## Why mcp-searxng? | | Brave MCP | Exa MCP | Firecrawl MCP | **mcp-searxng** | |--|:---------:|:-------:|:-------------:|:---------------:| | Web Search | โœ“ | โœ“ | โœ“ | โœ“ | | Read URL | โœ— | โœ“ | โœ“ | โœ“ | | Pagination | โœ— | โœ— | โœ“ | โœ“ | | Self-hosted | โœ— | โœ— | Partial | โœ“ | | Privacy | โœ— | โœ— | โœ— | โœ“ | | Free / No API key | โœ— | โœ— | โœ— | โœ“ | ## How It Works `mcp-searxng` is a standalone MCP server โ€” a separate Node.js process that your AI assistant connects to for web search. It queries one SearXNG instance, or a semicolon-separated list of interchangeable SearXNG replicas, via the HTTP JSON API. > **Not a SearXNG plugin:** This project cannot be installed as a native SearXNG plugin. Point it at any existing SearXNG instance, or interchangeable replica list, by setting `SEARXNG_URL`. ``` AI Assistant (e.g. Claude) โ”‚ MCP protocol โ–ผ mcp-searxng (this project โ€” Node.js process) โ”‚ HTTP JSON API (SEARXNG_URL) โ–ผ SearXNG instance(s) ``` ## Tools - **searxng_web_search** - Execute web searches with pagination - Inputs: - `query` (string): The search query. This string is passed to external search services. - `pageno` (number, optional): Search page number, starts at 1 (default 1) - `time_range` (string, optional): Filter results by time range - one of: "day", "week", "month", "year" (default: none) - `language` (string, optional): Language code for results (e.g., "en", "fr", "de") or "all" (default: "all") - `safesearch` (string enum, optional): Safe search filter level, one of `"0"` (None), `"1"` (Moderate), or `"2"` (Strict). Legacy numeric values `0`, `1`, and `2` are still accepted for backward compatibility. (default: instance setting) - `min_score` (number, optional): Minimum relevance score from 0.0 to 1.0. Results below this score are filtered out. - `num_results` (number, optional): Maximum number of results to return, from 1 to 20. `SEARXNG_MAX_RESULTS` applies as an operator ceiling. - `categories` (string, optional): Comma-separated SearXNG categories (e.g. `"news"`, `"it,science"`). Live `/config` capabilities are aggregated across reachable instances; prefer `searxng_instance_info` `categories.common` for consistent multi-instance results. Known values are trimmed and normalized case-insensitively; unknown values are forwarded trimmed so SearXNG can ignore or honor them. If `/config` is unavailable, values are forwarded as-is with a warning. If omitted, each instance uses its server-side default. - `engines` (string, optional): Comma-separated SearXNG engine names (e.g. `"google,bing,ddg"`, `"semantic scholar"`). Live `/config` capabilities are aggregated across reachable instances; prefer `searxng_instance_info` `engines.common.enabled` for consistent multi-instance results. Known values are trimmed and normalized case-insensitively, including engines disabled by default; unknown values are forwarded trimmed so SearXNG can ignore or honor them. If `/config` is unavailable, values are forwarded as-is with a warning. If omitted, each instance uses its server-side default. - `response_format` (string, optional): Response format, either `"text"` for formatted agent-readable output or `"json"` for raw SearXNG JSON with filtered/sliced `results`. (default: `"text"`) - **searxng_search_suggestions** - Get autocomplete suggestions for refining search queries - Inputs: - `query` (string): Partial or complete query to autocomplete. - `language` (string, optional): Language code for suggestions (e.g., "en", "fr", "de") or "all" (default: "all") - **searxng_instance_info** - Discover categories, engines, defaults, locales, and plugins exposed by all reachable configured SearXNG instances. The response reports `common` values present on every reachable instance and `available` values present on at least one reachable instance. - Inputs: - `includeEngines` (boolean, optional): Include enabled engine names in the response. (default: false) - `includeDisabled` (boolean, optional): Include disabled engine names when `includeEngines` is true. (default: false) - `category` (string, optional): Filter categories and engines to a single category name. - `refresh` (boolean, optional): Bypass the process cache and fetch fresh `/config` data. (default: false) - **web_url_read** - Read and convert the content from a URL to markdown with advanced content extraction options - Inputs: - `url` (string): The URL to fetch and process - `startChar` (number, optional): Starting character position for content extraction (default: 0) - `maxLength` (number, optional): Maximum number of characters to return - `section` (string, optional): Extract content under a specific heading (searches for heading text) - `paragraphRange` (string, optional): Return specific paragraph ranges (e.g., '1-5', '3', '10-') - `readHeadings` (boolean, optional): Return only a list of headings instead of full content ## Installation NPM (global install) ```bash npm install -g mcp-searxng ``` ```json { "mcpServers": { "searxng": { "command": "mcp-searxng", "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL" } } } } ``` Docker **Pre-built image:** ```bash docker pull isokoliuk/mcp-searxng:latest ``` Image signatures can be verified with Cosign โ€” see [SECURITY.md](SECURITY.md) for instructions. ```json { "mcpServers": { "searxng": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "SEARXNG_URL", "isokoliuk/mcp-searxng:latest" ], "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL" } } } } ``` To pass additional env vars, add `-e VAR_NAME` to `args` and the variable to `env`. **Build locally:** ```bash docker build -t mcp-searxng:latest -f Dockerfile . ``` Use the same config above, replacing `isokoliuk/mcp-searxng:latest` with `mcp-searxng:latest`. Docker Compose `docker-compose.yml`: ```yaml services: mcp-searxng: image: isokoliuk/mcp-searxng:latest stdin_open: true environment: - SEARXNG_URL=YOUR_SEARXNG_INSTANCE_URL # Add optional variables as needed โ€” see CONFIGURATION.md ``` MCP client config: ```json { "mcpServers": { "searxng": { "command": "docker-compose", "args": ["run", "--rm", "mcp-searxng"] } } } ``` HTTP Transport By default the server uses STDIO. Set `MCP_HTTP_PORT` to enable HTTP mode: ```json { "mcpServers": { "searxng-http": { "command": "mcp-searxng", "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL", "MCP_HTTP_PORT": "3000" } } } } ``` **Endpoints:** `POST/GET/DELETE /mcp` (MCP protocol), `GET /health` (health check) **Test it:** ```bash MCP_HTTP_PORT=3000 SEARXNG_URL=http://localhost:8080 mcp-searxng curl http://localhost:3000/health ``` ## Configuration Set `SEARXNG_URL` to your SearXNG instance URL. For failover, set it to semicolon-separated interchangeable replica URLs. Set `SEARXNG_FANOUT=true` to query all healthy replicas in parallel and merge results. All other variables are optional. Full environment variable reference: [CONFIGURATION.md](CONFIGURATION.md) ## Troubleshooting ### 403 Forbidden from SearXNG Your SearXNG instance likely has JSON format disabled. Edit `settings.yml` (usually `/etc/searxng/settings.yml`): ```yaml search: formats: - html - json ``` Restart SearXNG (`docker restart searxng`) then verify: ```bash curl 'http://localhost:8080/search?q=test&format=json' ``` You should receive a JSON response. If not, confirm the file is correctly mounted and YAML indentation is valid. See also: [SearXNG settings docs](https://docs.searxng.org/admin/settings/settings.html) ยท [discussion](https://github.com/searxng/searxng/discussions/1789) ### Can't enable JSON? (HTML fallback) If you must use a public instance you don't control and it rejects `format=json` (the 403 above), set the opt-in flag instead of editing the server: ```json "SEARXNG_HTML_FALLBACK": "true" ``` A search that gets a `403`/`404` or a non-JSON response is then retried automatically **without** `format=json` and parsed from the regular HTML results page. - **On success:** you get normal results (title, URL, snippet). They are marked `sourceFormat: "html"` in JSON mode, and text mode adds the line *"Note: Results parsed from SearXNG HTML fallback; metadata is limited."* Relevance scores and engine names are not available from HTML. - **On failure:** parsing is best-effort and varies by the instance's theme/version, so some results may be missed or sparse. If the HTML page itself also fails โ€” still blocked, rate-limited (`429`), auth (`401`), or `5xx` โ€” the **original error is surfaced unchanged**. The fallback only triggers on `403`/`404`/non-JSON, never on auth or network errors. Enabling JSON on an instance you control (above) remains the recommended setup โ€” the fallback is a compatibility aid, not a replacement. ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) ## Star History ## License MIT โ€” see [LICENSE](LICENSE) for details. ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source โ€” we do not rehost the code. - **Author:** [ihor-sokoliuk](https://github.com/ihor-sokoliuk) - **Source:** [ihor-sokoliuk/mcp-searxng](https://github.com/ihor-sokoliuk/mcp-searxng) - **License:** MIT - **Homepage:** https://www.npmjs.com/package/mcp-searxng Install and usage instructions live in the source repository linked above. ## Pricing - **Free** โ€” Free ## Security capabilities Automated source analysis of v0.1.0 โ€” what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source โ€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** โ€” security scan: passed โ€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-ihor-sokoliuk-mcp-searxng - Seller: https://agentstack.voostack.com/s/ihor-sokoliuk - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack โ€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.