中文 | Deutsch | English | Español | français | 日本語 | 한국어 | Português | Русский

SearXNG MCP Server

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