Skip to content
Back to search

mcp-searxng

Private web search for AI assistants via SearXNG — supports Claude, Cursor, and any MCP client

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ihor-sokoliuk/mcp-searxng with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ihor-sokoliuk/mcp-searxng'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ihor-sokoliuk--mcp-searxng/badge.svg)](/listings/ihor-sokoliuk--mcp-searxng)

HTML

<a href="/listings/ihor-sokoliuk--mcp-searxng"><img src="/api/listings/ihor-sokoliuk--mcp-searxng/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need an existing **SearXNG instance with JSON search enabled**. This project connects an MCP client to SearXNG; it does not install SearXNG. Use an instance you operate or trust. Start with the [self-hosted](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/self-hosted-searxng.md) or [public-instance](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/public-searxng-instances.md) guide if needed.

Choose how to connect:

| Your setup | Start here | |---|---| | Client starts the server locally | Install Node.js 22 or later, then use the NPX example below or your client recipe. | | Client starts a Docker container | Use the Docker/STDIO recipe in [Installation](#installation). | | You have an independently running HTTP service | Use your client's HTTP recipe with the full `/mcp` URL. | | You need to operate an HTTP service | Follow the [HTTP server guide](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/http-server.md). |

For clients using `mcpServers` JSON (such as Claude Desktop), add:

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": { "SEARXNG_URL": "https://search.example.com" }
    }
  }
}

Replace the example URL with your SearXNG base URL. Other clients use different configuration shapes: choose [your client recipe](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/client-configurations.md). Leave `MCP_HTTP_PORT` unset for local STDIO. Docker also needs environment forwarding into the container.

Reload the client, inspect its MCP tool inventory, then ask it to search for SearXNG documentation. A simple tool call is `searxng_web_search` with `{"query":"SearXNG"}`. Discovery alone does not test SearXNG connectivity. If the call fails, start with [troubleshooting](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 332 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # 🔍 SearXNG MCP Server
  3. **Privacy-respecting web search for AI assistants — use an operator-controlled or trusted SearXNG instance with Claude, Cursor, and more.**
  4. [![GitHub Stars](https://img.shields.io/github/stars/ihor-sokoliuk/mcp-searxng?style=flat-square&logo=github&label=stars)](https://github.com/ihor-sokoliuk/mcp-searxng/stargazers)
  5. [![npm version](https://img.shields.io/npm/v/mcp-searxng?style=flat-square&logo=npm)](https://www.npmjs.com/package/mcp-searxng)
  6. [![npm downloads](https://img.shields.io/npm/dm/mcp-searxng?style=flat-square&logo=npm&label=downloads%2Fmo)](https://www.npmjs.com/package/mcp-searxng)
  7. [![Docker Pulls](https://img.shields.io/docker/pulls/isokoliuk/mcp-searxng?style=flat-square&logo=docker)](https://hub.docker.com/r/isokoliuk/mcp-searxng)
  8. [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
  9. [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ihor-sokoliuk/mcp-searxng/badge)](https://scorecard.dev/viewer/?uri=github.com/ihor-sokoliuk/mcp-searxng)
  10. [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13143/badge)](https://www.bestpractices.dev/projects/13143)
  11. [![mcp-searxng MCP server](https://glama.ai/mcp/servers/ihor-sokoliuk/mcp-searxng/badges/score.svg)](https://glama.ai/mcp/servers/ihor-sokoliuk/mcp-searxng)
  12. [![GitHub MCP Registry](https://img.shields.io/badge/GitHub_MCP_Registry-listed-2da44e?style=flat-square&logo=github&logoColor=white)](https://github.com/mcp/ihor-sokoliuk/mcp-searxng)
  13. An [MCP server](https://modelcontextprotocol.io/introduction) that integrates the [SearXNG](https://docs.searxng.org) API, giving AI assistants web search capabilities.
  14. ✨ Featured in the [GitHub MCP Registry](https://github.com/mcp/ihor-sokoliuk/mcp-searxng).
  15. </div>
  16. ## Quick Start
  17. You need an existing **SearXNG instance with JSON search enabled**. This project
  18. connects an MCP client to SearXNG; it does not install SearXNG. Use an instance
  19. you operate or trust. Start with the [self-hosted](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/self-hosted-searxng.md)
  20. or [public-instance](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/public-searxng-instances.md) guide if needed.
  21. Choose how to connect:
  22. | Your setup | Start here |
  23. |---|---|
  24. | Client starts the server locally | Install Node.js 22 or later, then use the NPX example below or your client recipe. |
  25. | Client starts a Docker container | Use the Docker/STDIO recipe in [Installation](#installation). |
  26. | You have an independently running HTTP service | Use your client's HTTP recipe with the full `/mcp` URL. |
  27. | You need to operate an HTTP service | Follow the [HTTP server guide](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/http-server.md). |
  28. For clients using `mcpServers` JSON (such as Claude Desktop), add:
  29. ```json
  30. {
  31. "mcpServers": {
  32. "searxng": {
  33. "command": "npx",
  34. "args": ["-y", "mcp-searxng"],
  35. "env": { "SEARXNG_URL": "https://search.example.com" }
  36. }
  37. }
  38. }
  39. ```
  40. Replace the example URL with your SearXNG base URL. Other clients use different
  41. configuration shapes: choose [your client recipe](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/client-configurations.md).
  42. Leave `MCP_HTTP_PORT` unset for local STDIO. Docker also needs environment
  43. forwarding into the container.
  44. Reload the client, inspect its MCP tool inventory, then ask it to search for
  45. SearXNG documentation. A simple tool call is
  46. `searxng_web_search` with `{"query":"SearXNG"}`. Discovery alone does not
  47. test SearXNG connectivity. If the call fails, start with
  48. [troubleshooting](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md).
  49. ## Features
  50. - Search with pagination, filters, direct answers and full or compact text/JSON output.
  51. - Find images with `categories="images"` and `result_detail="full"`, including available image URLs, thumbnails and resolution.
  52. - Read HTML, structured text and bounded PDF text; inspect headings or selected sections.
  53. - Discover instance capabilities and get query suggestions.
  54. - Optional replica failover/fan-out, HTML fallback, caching, proxies and browser solvers.
  55. - Local STDIO or Streamable HTTP, with static bearer and optional OAuth protection.
  56. See the [tool guide](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/tools.md) for capabilities and limits,
  57. [configuration reference](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/CONFIGURATION.md) for settings, and
  58. [historical deployment measurements](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/deployment-profiles.md) for
  59. bounded resource-planning evidence.
  60. ## Why mcp-searxng?
  61. <details>
  62. <summary>Capability comparison recorded on 2026-07-29</summary>
  63. As of 2026-07-29, the capability comparison below reflects the official
  64. [Brave MCP](https://github.com/brave/brave-search-mcp-server),
  65. [Exa MCP](https://github.com/exa-labs/exa-mcp-server), and
  66. [Firecrawl MCP](https://github.com/mendableai/firecrawl-mcp-server) projects.
  67. “Pagination” means an exposed page or offset control. “Self-hosted” means the
  68. search service can run under your control. “Free / No API key” means this MCP
  69. server does not require a paid search-vendor API key; you still operate or
  70. select the underlying SearXNG instance.
  71. | | Brave MCP | Exa MCP | Firecrawl MCP | **mcp-searxng** |
  72. |--|:---------:|:-------:|:-------------:|:---------------:|
  73. | Web Search | ✓ | ✓ | ✓ | ✓ |
  74. | Read URL | ✗ | ✓ | ✓ | ✓ |
  75. | Pagination | ✓ | ✗ | ✓ | ✓ |
  76. | Self-hosted | ✗ | ✗ | Partial | ✓ |
  77. | Free / No API key | ✗ | ✗ | ✗ | ✓ |
  78. </details>
  79. Privacy depends on the SearXNG deployment. An operator-controlled instance can
  80. avoid trusting a third-party search operator, while a public instance receives
  81. the query and may log it. SearXNG and this MCP integration do not by themselves
  82. provide anonymity.
  83. ## How It Works
  84. `MCP client → mcp-searxng → SearXNG → search engines`
  85. The client either starts its own STDIO process or connects to an HTTP service.
  86. `SEARXNG_URL` identifies the SearXNG service, not the MCP endpoint. URL reading
  87. fetches the selected website directly. A semicolon-separated replica list is
  88. supported for interchangeable SearXNG deployments; see
  89. [replica configuration](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/CONFIGURATION.md#core).
  90. STDIO is the default. Legacy Streamable HTTP sessions are stateful by default:
  91. clients should send `DELETE /mcp` when finished, then reinitialize if a later
  92. request receives HTTP 404 for the terminated session. Modern HTTP requests and
  93. the `MCP_HTTP_STATELESS=true` legacy mode are sessionless; see
  94. [HTTP transport configuration](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/CONFIGURATION.md#http-transport).
  95. ## Tools
  96. | Tool | Use it to |
  97. |---|---|
  98. | `searxng_web_search` | Find sources and refine results |
  99. | `searxng_search_suggestions` | Complete or refine a query |
  100. | `searxng_instance_info` | Inspect categories, engines and defaults |
  101. | `web_url_read` | Read a known URL as text/Markdown |
  102. The [tool guide](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/tools.md) contains examples and the full parameter
  103. reference. The optional [research workflow](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/research-workflow.md)
  104. explains how to inspect sources and cite evidence.
  105. ## Installation
  106. The project-maintained distribution methods are **npm** (including **npx**)
  107. and **Docker**. Additional package formats, including Nix, can be maintained
  108. separately by the community.
  109. For NPX and npm installs, Node.js 22 or later is required. The Docker image
  110. includes its Node.js runtime.
  111. <details>
  112. <summary>NPM (global install)</summary>
  113. ```bash
  114. npm install -g mcp-searxng
  115. ```
  116. ```json
  117. {
  118. "mcpServers": {
  119. "searxng": {
  120. "command": "mcp-searxng",
  121. "env": {
  122. "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
  123. }
  124. }
  125. }
  126. }
  127. ```
  128. </details>
  129. <details>
  130. <summary>Docker</summary>
  131. **Pre-built image:**
  132. ```bash
  133. docker pull isokoliuk/mcp-searxng:latest
  134. ```
  135. Image signatures can be verified with Cosign — see [SECURITY.md](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/SECURITY.md) for instructions.
  136. ```json
  137. {
  138. "mcpServers": {
  139. "searxng": {
  140. "command": "docker",
  141. "args": [
  142. "run", "-i", "--rm",
  143. "-e", "SEARXNG_URL",
  144. "isokoliuk/mcp-searxng:latest"
  145. ],
  146. "env": {
  147. "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
  148. }
  149. }
  150. }
  151. }
  152. ```
  153. To pass additional env vars, add `-e VAR_NAME` to `args` and the variable to `env`.
  154. For browser-solver integration, pass `FLARESOLVERR_URL`, `BYPARR_URL`, or both
  155. and make the configured services reachable from this container. Dual mode has
  156. a fixed FlareSolverr-first order and no automatic reverse failover. Safe rendered
  157. HTML and explicit Byparr PDF content are read directly; ambiguous content uses
  158. guarded replay, with bounded failover for eligible read failures. See
  159. [URL Reader Controls](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/CONFIGURATION.md#url-reader-controls) for the complete
  160. behavior and Docker Compose example.
  161. **Build locally:**
  162. ```bash
  163. docker build -t mcp-searxng:latest -f Dockerfile .
  164. ```
  165. Use the same config above, replacing `isokoliuk/mcp-searxng:latest` with `mcp-searxng:latest`.
  166. </details>
  167. <details>
  168. <summary>Docker Compose</summary>
  169. `docker-compose.yml`:
  170. ```yaml
  171. services:
  172. mcp-searxng:
  173. image: isokoliuk/mcp-searxng:latest
  174. stdin_open: true
  175. environment:
  176. - SEARXNG_URL=${SEARXNG_URL:?Set SEARXNG_URL in the environment}
  177. # Add optional variables as needed — see CONFIGURATION.md
  178. ```
  179. The tracked Compose file is intentionally STDIO-only and publishes no network ports; MCP clients launch it with an absolute Compose-file path and `docker compose run --rm -T`, not `docker compose up`. The `-T` flag prevents pseudo-TTY allocation so MCP JSON-RPC stays on raw standard input and output. Compose fails before launch unless the MCP client supplies `SEARXNG_URL`.
  180. MCP client config:
  181. ```json
  182. {
  183. "mcpServers": {
  184. "searxng": {
  185. "command": "docker",
  186. "args": [
  187. "compose",
  188. "-f", "/absolute/path/to/docker-compose.yml",
  189. "run", "--rm", "-T", "mcp-searxng"
  190. ],
  191. "env": {
  192. "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
  193. }
  194. }
  195. }
  196. }
  197. ```
  198. If you previously used the tracked file as an HTTP service on port 8080, put the HTTP settings in an untracked `docker-compose.override.yml`:
  199. ```yaml
  200. services:
  201. mcp-searxng:
  202. ports:
  203. - "127.0.0.1:8080:8080"
  204. environment:
  205. - MCP_HTTP_PORT=8080
  206. - MCP_HTTP_HOST=0.0.0.0
  207. ```
  208. Here `0.0.0.0` is the container-side bind address; the host-side port remains loopback-only. This override has no authentication and is only a temporary single-host migration path. Before adding co-located containers or exposing the service beyond the local machine, follow the hardened [deployment guidance](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/SECURITY.md#deployment-recommendations).
  209. </details>
  210. ### HTTP Transport
  211. Run HTTP independently, then connect the client. See the
  212. [HTTP server guide](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/http-server.md) for local checks, static bearer
  213. authentication, OAuth requirements and deployment verification.
  214. ## Configuration
  215. For the default local setup, `SEARXNG_URL` is the required setting. Optional
  216. modes such as hardened HTTP and OAuth have companion requirements. Use the
  217. [configuration reference](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/CONFIGURATION.md) for environment variables,
  218. defaults, caching, timeouts, proxies, TLS, and limits.
  219. ### Optional MCP OAuth
  220. An HTTP deployment can use OAuth with an external authorization provider.
  221. See [authentication choices](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/http-server.md#choose-authentication).
  222. Static bearer authentication and SearXNG Basic Auth protect different connections.
  223. ## Troubleshooting
  224. | Symptom | Next check |
  225. |---|---|
  226. | Server absent or disconnected | [Client/process startup](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md#client-and-process) |
  227. | HTTP auth, session or proxy error | [HTTP connection](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md#http-connection) |
  228. | Tools appear but search fails | [SearXNG connection](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md#search-and-searxng) |
  229. | Empty, poor or stale results | [Filters, upstream metadata and cache](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md#result-quality-and-cache) |
  230. | URL/PDF failure or timeout | [URL reading](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md#url-reading) |
  231. ### 403 Forbidden from SearXNG
  232. JSON output may be disabled, or an access-control layer may have denied the
  233. request. Follow the [direct checks](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/self-hosted-searxng.md#verify-searxng-directly)
  234. before changing settings. A working browser page does not prove the JSON API works.
  235. ### Can't enable JSON? (HTML fallback)
  236. `SEARXNG_HTML_FALLBACK=true` can retry 403/404/non-JSON search responses as HTML.
  237. Parsing is best-effort and metadata is limited; compact output omits fallback
  238. markers. Read the [public-instance guidance](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/public-searxng-instances.md#json-rejection-and-html-fallback)
  239. before enabling it on a service you do not control.
  240. For a bug report, [collect a minimal reproduction and relevant errors](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/troubleshooting.md#collect-useful-evidence).
  241. ## Documentation
  242. [Configure search for useful coverage](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/search-configuration.md)
  243. with tested upstream settings, specialist engine routes and MCP output controls.
  244. The [deployment recipe](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/browser-solver-deployment.md)
  245. includes a private Compose stack and optional browser providers, with dated
  246. results and known failures.
  247. [Find a guide by task](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/docs/index.md). These links open current main-branch
  248. documentation. Unreleased behavior is labeled; consult the matching Git tag
  249. when investigating an older version.
  250. ## Contributing
  251. See [CONTRIBUTING.md](https://github.com/ihor-sokoliuk/mcp-searxng/blob/main/CONTRIBUTING.md).
  252. ## License
  253. MIT — see [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.