Skip to content
Back to search

searxng-mul-mcp

A Model Context Protocol (MCP) server for SearXNG search engine with multi-query parallel search support

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

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

HTML

<a href="/listings/jae-jae--searxng-mul-mcp"><img src="/api/listings/jae-jae--searxng-mul-mcp/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.

NPM Usage

Stdio Mode (Default)

SEARXNG_URL=https://your.searxng.com npx -y searxng-mul-mcp

HTTP Mode

SEARXNG_URL=https://your.searxng.com npx -y searxng-mul-mcp --transport=http --host=0.0.0.0 --port=3000

Environment Variables

# Required: SearXNG server URL
SEARXNG_URL=https://your.searxng.com

# Optional: Basic Auth credentials
USERNAME=your_username
PASSWORD=your_password

# Optional: Transport configuration (can also use CLI flags)
TRANSPORT=stdio|http
HOST=0.0.0.0        # HTTP mode only
PORT=3000           # HTTP mode only

# Optional: Debug mode
DEBUG=false

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 · 310 lines

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

  1. [中文](https://zdoc.app/zh/jae-jae/searxng-mul-mcp) |
  2. [Deutsch](https://zdoc.app/de/jae-jae/searxng-mul-mcp) |
  3. [English](https://zdoc.app/en/jae-jae/searxng-mul-mcp) |
  4. [Español](https://zdoc.app/es/jae-jae/searxng-mul-mcp) |
  5. [français](https://zdoc.app/fr/jae-jae/searxng-mul-mcp) |
  6. [日本語](https://zdoc.app/ja/jae-jae/searxng-mul-mcp) |
  7. [한국어](https://zdoc.app/ko/jae-jae/searxng-mul-mcp) |
  8. [Português](https://zdoc.app/pt/jae-jae/searxng-mul-mcp) |
  9. [Русский](https://zdoc.app/ru/jae-jae/searxng-mul-mcp)
  10. # SearXNG Mul MCP
  11. A Model Context Protocol (MCP) server for SearXNG metasearch engine integration, supporting multi-query parallel search with both stdio and HTTP transport protocols.
  12. > 🌟 **Recommended**: [OllaMan](https://ollaman.com/) - Powerful Ollama AI Model Manager.
  13. ## Features
  14. - ✅ **Multi-Query Parallel Search**: Execute multiple search queries simultaneously for improved efficiency
  15. - ✅ **Dual Transport Support**: Compatible with both stdio and HTTP MCP transport protocols
  16. - ✅ **SearXNG API Integration**: Direct integration with SearXNG REST API without browser automation
  17. - ✅ **Basic Authentication**: Support for SearXNG servers with Basic Auth protection
  18. - ✅ **Docker Deployment**: Complete containerization with Docker and Docker Compose
  19. - ✅ **Environment Configuration**: Flexible configuration management through environment variables
  20. ## Quick Start
  21. ### NPM Usage
  22. #### Stdio Mode (Default)
  23. ```bash
  24. SEARXNG_URL=https://your.searxng.com npx -y searxng-mul-mcp
  25. ```
  26. #### HTTP Mode
  27. ```bash
  28. SEARXNG_URL=https://your.searxng.com npx -y searxng-mul-mcp --transport=http --host=0.0.0.0 --port=3000
  29. ```
  30. ### Environment Variables
  31. ```bash
  32. # Required: SearXNG server URL
  33. SEARXNG_URL=https://your.searxng.com
  34. # Optional: Basic Auth credentials
  35. USERNAME=your_username
  36. PASSWORD=your_password
  37. # Optional: Transport configuration (can also use CLI flags)
  38. TRANSPORT=stdio|http
  39. HOST=0.0.0.0 # HTTP mode only
  40. PORT=3000 # HTTP mode only
  41. # Optional: Debug mode
  42. DEBUG=false
  43. ```
  44. ## Configuration
  45. ### Claude Desktop Configuration
  46. Add the following configuration to your Claude Desktop `claude_desktop_config.json` file:
  47. stdio mode:
  48. ```json
  49. {
  50. "mcpServers": {
  51. "searxng-mul-mcp": {
  52. "command": "npx",
  53. "args": ["-y", "searxng-mul-mcp"],
  54. "env": {
  55. "SEARXNG_URL": "https://your.searxng.com",
  56. "USERNAME": "your_username",
  57. "PASSWORD": "your_password"
  58. }
  59. }
  60. }
  61. }
  62. ```
  63. ### SearXNG Server Setup
  64. This MCP server requires access to a SearXNG instance. You can:
  65. 1. Use a public SearXNG instance (like `https://your.searxng.com`)
  66. 2. Deploy your own SearXNG server
  67. 3. Use a private SearXNG instance with Basic Auth
  68. ### Basic Authentication
  69. If your SearXNG server requires Basic Auth:
  70. ```bash
  71. export USERNAME=your_username
  72. export PASSWORD=your_password
  73. ```
  74. ### Transport Protocols
  75. #### Stdio Transport
  76. - Default mode for MCP client integration
  77. - Uses standard input/output for communication
  78. - Suitable for direct MCP client connections
  79. #### HTTP Transport
  80. - Provides StreamableHTTP JSON-RPC interface (protocol version 2025-03-26)
  81. - Includes health check endpoint at `/health`
  82. - MCP endpoint at `/mcp` for client communication
  83. - Supports session management with automatic cleanup
  84. - Full CORS support for cross-origin requests
  85. - Suitable for web-based integrations and modern MCP clients
  86. ## Installation
  87. ### From Source
  88. ```bash
  89. git clone <repository-url>
  90. cd searxng-mul-mcp
  91. npm install
  92. npm run build
  93. npm start
  94. ```
  95. ### Docker Deployment
  96. Create a `docker-compose.yml` file:
  97. ```yaml
  98. services:
  99. searxng-mul-mcp:
  100. image: ghcr.io/jae-jae/searxng-mul-mcp:latest
  101. environment:
  102. - SEARXNG_URL=https://your.searxng.com
  103. # Optional: Basic Auth
  104. # - USERNAME=your_username
  105. # - PASSWORD=your_password
  106. ports:
  107. - "3000:3000"
  108. ```
  109. Run with:
  110. ```bash
  111. docker-compose up -d
  112. ```
  113. ## MCP Tool Usage
  114. The server provides a single `search` tool that accepts the following parameters:
  115. #### Parameters
  116. - **queries** (required): Array of search query strings to execute in parallel
  117. - **engines** (optional): Specific search engines to use (e.g., "google", "bing", "duckduckgo")
  118. - **categories** (optional): Search categories to filter results (e.g., "general", "images", "news")
  119. - **safesearch** (optional): Safe search level (0=off, 1=moderate, 2=strict)
  120. - **language** (optional): Search language code (e.g., "en", "zh", "es")
  121. ## Development
  122. ### Prerequisites
  123. - Node.js 18 or higher
  124. - npm or yarn
  125. - TypeScript
  126. ### Build Commands
  127. ```bash
  128. # Install dependencies
  129. npm install
  130. # Build TypeScript
  131. npm run build
  132. # Start development server
  133. npm run dev
  134. # Run in production
  135. npm start
  136. # Clean build directory
  137. npm run clean
  138. # Run tests
  139. npm test
  140. # Lint code
  141. npm run lint
  142. # Format code
  143. npm run format
  144. ```
  145. ### Project Structure
  146. ```
  147. searxng-mul-mcp/
  148. ├── src/
  149. │ ├── index.ts # Application entry point
  150. │ ├── server.ts # MCP server core logic
  151. │ ├── config/
  152. │ │ └── index.ts # Configuration management
  153. │ ├── tools/
  154. │ │ ├── index.ts # Tool definitions
  155. │ │ └── searxng.ts # SearXNG search tool implementation
  156. │ ├── transports/
  157. │ │ ├── index.ts # Transport factory
  158. │ │ ├── stdio.ts # Stdio transport implementation
  159. │ │ ├── http.ts # HTTP transport implementation
  160. │ │ └── types.ts # Transport type definitions
  161. │ ├── services/
  162. │ │ └── searxng-api.ts # SearXNG API client
  163. │ └── utils/
  164. │ └── logger.ts # Logging utilities
  165. ├── build/ # TypeScript compilation output
  166. ├── package.json # Project dependencies and scripts
  167. ├── tsconfig.json # TypeScript configuration
  168. ├── Dockerfile # Docker image build
  169. ├── docker-compose.yml # Docker Compose configuration
  170. └── README.md # This file
  171. ```
  172. ## API Reference
  173. ### SearXNG API Integration
  174. This server integrates with the SearXNG search API. For more information about SearXNG API capabilities, see: https://docs.searxng.org/dev/search_api.html
  175. ### Error Handling
  176. The server implements comprehensive error handling:
  177. - **Network errors**: Automatic retry mechanism (up to 3 attempts)
  178. - **Authentication errors**: Clear error messages for auth failures
  179. - **API rate limiting**: Graceful degradation and error reporting
  180. - **Timeout handling**: Configurable request timeout (default: 30 seconds)
  181. ## Monitoring
  182. ### Health Checks
  183. HTTP mode provides a health check endpoint:
  184. ```bash
  185. curl http://localhost:3000/health
  186. ```
  187. Response:
  188. ```json
  189. {
  190. "status": "healthy",
  191. "timestamp": "2024-01-01T00:00:00.000Z",
  192. "version": "1.0.0"
  193. }
  194. ```
  195. ### Logging
  196. The server provides structured logging with configurable levels:
  197. - **ERROR**: Critical errors and failures
  198. - **WARN**: Warning messages and degraded functionality
  199. - **INFO**: General operational information
  200. - **DEBUG**: Detailed debugging information (enable with `DEBUG=true`)
  201. ## Troubleshooting
  202. ### Common Issues
  203. 1. **Connection Failed**: Check your `SEARXNG_URL` and network connectivity
  204. 2. **Authentication Error**: Verify `USERNAME` and `PASSWORD` for Basic Auth
  205. 3. **Port Already in Use**: Change the `PORT` environment variable for HTTP mode
  206. 4. **Search Timeout**: Increase timeout or check SearXNG server performance
  207. ### Debug Mode
  208. Enable debug logging for detailed troubleshooting:
  209. ```bash
  210. DEBUG=true npx searxng-mul-mcp
  211. ```
  212. ## License
  213. MIT License - see LICENSE file for details.
  214. ## Contributing
  215. 1. Fork the repository
  216. 2. Create a feature branch
  217. 3. Make your changes
  218. 4. Add tests if applicable
  219. 5. Submit a pull request
  220. ## Support
  221. For issues and questions:
  222. 1. Check the troubleshooting section
  223. 2. Review SearXNG documentation
  224. 3. Open an issue on GitHub

Ratings and comments

Sign in to rate this skill.

Sign in

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