Content
[中文](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
