Back to search
searxng-mul-mcp
MCP serverGitHub
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
Markdown
[](/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)
- [中文](https://zdoc.app/zh/jae-jae/searxng-mul-mcp) |
- [Deutsch](https://zdoc.app/de/jae-jae/searxng-mul-mcp) |
- [English](https://zdoc.app/en/jae-jae/searxng-mul-mcp) |
- [Español](https://zdoc.app/es/jae-jae/searxng-mul-mcp) |
- [français](https://zdoc.app/fr/jae-jae/searxng-mul-mcp) |
- [日本語](https://zdoc.app/ja/jae-jae/searxng-mul-mcp) |
- [한국어](https://zdoc.app/ko/jae-jae/searxng-mul-mcp) |
- [Português](https://zdoc.app/pt/jae-jae/searxng-mul-mcp) |
- [Русский](https://zdoc.app/ru/jae-jae/searxng-mul-mcp)
- # SearXNG Mul MCP
- A Model Context Protocol (MCP) server for SearXNG metasearch engine integration, supporting multi-query parallel search with both stdio and HTTP transport protocols.
- > 🌟 **Recommended**: [OllaMan](https://ollaman.com/) - Powerful Ollama AI Model Manager.
- ## Features
- - ✅ **Multi-Query Parallel Search**: Execute multiple search queries simultaneously for improved efficiency
- - ✅ **Dual Transport Support**: Compatible with both stdio and HTTP MCP transport protocols
- - ✅ **SearXNG API Integration**: Direct integration with SearXNG REST API without browser automation
- - ✅ **Basic Authentication**: Support for SearXNG servers with Basic Auth protection
- - ✅ **Docker Deployment**: Complete containerization with Docker and Docker Compose
- - ✅ **Environment Configuration**: Flexible configuration management through environment variables
- ## Quick Start
- ### NPM Usage
- #### Stdio Mode (Default)
- ```bash
- SEARXNG_URL=https://your.searxng.com npx -y searxng-mul-mcp
- ```
- #### HTTP Mode
- ```bash
- SEARXNG_URL=https://your.searxng.com npx -y searxng-mul-mcp --transport=http --host=0.0.0.0 --port=3000
- ```
- ### Environment Variables
- ```bash
- # 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
- ```
- ## Configuration
- ### Claude Desktop Configuration
- Add the following configuration to your Claude Desktop `claude_desktop_config.json` file:
- stdio mode:
- ```json
- {
- "mcpServers": {
- "searxng-mul-mcp": {
- "command": "npx",
- "args": ["-y", "searxng-mul-mcp"],
- "env": {
- "SEARXNG_URL": "https://your.searxng.com",
- "USERNAME": "your_username",
- "PASSWORD": "your_password"
- }
- }
- }
- }
- ```
- ### SearXNG Server Setup
- This MCP server requires access to a SearXNG instance. You can:
- 1. Use a public SearXNG instance (like `https://your.searxng.com`)
- 2. Deploy your own SearXNG server
- 3. Use a private SearXNG instance with Basic Auth
- ### Basic Authentication
- If your SearXNG server requires Basic Auth:
- ```bash
- export USERNAME=your_username
- export PASSWORD=your_password
- ```
- ### Transport Protocols
- #### Stdio Transport
- - Default mode for MCP client integration
- - Uses standard input/output for communication
- - Suitable for direct MCP client connections
- #### HTTP Transport
- - Provides StreamableHTTP JSON-RPC interface (protocol version 2025-03-26)
- - Includes health check endpoint at `/health`
- - MCP endpoint at `/mcp` for client communication
- - Supports session management with automatic cleanup
- - Full CORS support for cross-origin requests
- - Suitable for web-based integrations and modern MCP clients
- ## Installation
- ### From Source
- ```bash
- git clone <repository-url>
- cd searxng-mul-mcp
- npm install
- npm run build
- npm start
- ```
- ### Docker Deployment
- Create a `docker-compose.yml` file:
- ```yaml
- services:
- searxng-mul-mcp:
- image: ghcr.io/jae-jae/searxng-mul-mcp:latest
- environment:
- - SEARXNG_URL=https://your.searxng.com
- # Optional: Basic Auth
- # - USERNAME=your_username
- # - PASSWORD=your_password
- ports:
- - "3000:3000"
- ```
- Run with:
- ```bash
- docker-compose up -d
- ```
- ## MCP Tool Usage
- The server provides a single `search` tool that accepts the following parameters:
- #### Parameters
- - **queries** (required): Array of search query strings to execute in parallel
- - **engines** (optional): Specific search engines to use (e.g., "google", "bing", "duckduckgo")
- - **categories** (optional): Search categories to filter results (e.g., "general", "images", "news")
- - **safesearch** (optional): Safe search level (0=off, 1=moderate, 2=strict)
- - **language** (optional): Search language code (e.g., "en", "zh", "es")
- ## Development
- ### Prerequisites
- - Node.js 18 or higher
- - npm or yarn
- - TypeScript
- ### Build Commands
- ```bash
- # Install dependencies
- npm install
- # Build TypeScript
- npm run build
- # Start development server
- npm run dev
- # Run in production
- npm start
- # Clean build directory
- npm run clean
- # Run tests
- npm test
- # Lint code
- npm run lint
- # Format code
- npm run format
- ```
- ### Project Structure
- ```
- searxng-mul-mcp/
- ├── src/
- │ ├── index.ts # Application entry point
- │ ├── server.ts # MCP server core logic
- │ ├── config/
- │ │ └── index.ts # Configuration management
- │ ├── tools/
- │ │ ├── index.ts # Tool definitions
- │ │ └── searxng.ts # SearXNG search tool implementation
- │ ├── transports/
- │ │ ├── index.ts # Transport factory
- │ │ ├── stdio.ts # Stdio transport implementation
- │ │ ├── http.ts # HTTP transport implementation
- │ │ └── types.ts # Transport type definitions
- │ ├── services/
- │ │ └── searxng-api.ts # SearXNG API client
- │ └── utils/
- │ └── logger.ts # Logging utilities
- ├── build/ # TypeScript compilation output
- ├── package.json # Project dependencies and scripts
- ├── tsconfig.json # TypeScript configuration
- ├── Dockerfile # Docker image build
- ├── docker-compose.yml # Docker Compose configuration
- └── README.md # This file
- ```
- ## API Reference
- ### SearXNG API Integration
- This server integrates with the SearXNG search API. For more information about SearXNG API capabilities, see: https://docs.searxng.org/dev/search_api.html
- ### Error Handling
- The server implements comprehensive error handling:
- - **Network errors**: Automatic retry mechanism (up to 3 attempts)
- - **Authentication errors**: Clear error messages for auth failures
- - **API rate limiting**: Graceful degradation and error reporting
- - **Timeout handling**: Configurable request timeout (default: 30 seconds)
- ## Monitoring
- ### Health Checks
- HTTP mode provides a health check endpoint:
- ```bash
- curl http://localhost:3000/health
- ```
- Response:
- ```json
- {
- "status": "healthy",
- "timestamp": "2024-01-01T00:00:00.000Z",
- "version": "1.0.0"
- }
- ```
- ### Logging
- The server provides structured logging with configurable levels:
- - **ERROR**: Critical errors and failures
- - **WARN**: Warning messages and degraded functionality
- - **INFO**: General operational information
- - **DEBUG**: Detailed debugging information (enable with `DEBUG=true`)
- ## Troubleshooting
- ### Common Issues
- 1. **Connection Failed**: Check your `SEARXNG_URL` and network connectivity
- 2. **Authentication Error**: Verify `USERNAME` and `PASSWORD` for Basic Auth
- 3. **Port Already in Use**: Change the `PORT` environment variable for HTTP mode
- 4. **Search Timeout**: Increase timeout or check SearXNG server performance
- ### Debug Mode
- Enable debug logging for detailed troubleshooting:
- ```bash
- DEBUG=true npx searxng-mul-mcp
- ```
- ## License
- MIT License - see LICENSE file for details.
- ## Contributing
- 1. Fork the repository
- 2. Create a feature branch
- 3. Make your changes
- 4. Add tests if applicable
- 5. Submit a pull request
- ## Support
- For issues and questions:
- 1. Check the troubleshooting section
- 2. Review SearXNG documentation
- 3. Open an issue on GitHub
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.