searxng-mul-mcp

jae-jae/searxng-mul-mcp

3.5

If you are the rightful owner of searxng-mul-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The SearXNG MCP Server is a Model Context Protocol server designed for integrating with the SearXNG metasearch engine, enabling efficient multi-query parallel searches using both stdio and HTTP transport protocols.

δΈ­ζ–‡ | Deutsch | English | EspaΓ±ol | franΓ§ais | ζ—₯本θͺž | ν•œκ΅­μ–΄ | PortuguΓͺs | Русский

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 - 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)
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

Configuration

Claude Desktop Configuration

Add the following configuration to your Claude Desktop claude_desktop_config.json file:

stdio mode:

{
  "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:

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

git clone <repository-url>
cd searxng-mul-mcp
npm install
npm run build
npm start

Docker Deployment

Create a docker-compose.yml file:

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:

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

# 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:

curl http://localhost:3000/health

Response:

{
  "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:

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