searxng-mcp

jae-jae/searxng-mcp

3.2

If you are the rightful owner of searxng-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.

Tools
1
Resources
0
Prompts
0

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.

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)
npx -y searxng-mcp
HTTP Mode
npx -y searxng-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

Installation

From Source

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

Docker Deployment

Create a docker-compose.yml file:

services:
  searxng-mcp:
    image: ghcr.io/jae-jae/searxng-mcp:latest
    environment:
      - SEARXNG_URL=https://your.searxng.com
      # Optional: Basic Auth
      # - USERNAME=your_username
      # - PASSWORD=your_password
    ports:
      - "3000:3000"
    environment:
      - TRANSPORT=http
      - HOST=0.0.0.0
      - PORT=3000

Run with:

docker-compose up -d

MCP Tool Usage

The server provides a single search tool that accepts the following parameters:

Search Tool

{
  "name": "search",
  "arguments": {
    "queries": [
      "Brother printers review",
      "Brother printers features",
      "Brother printers types"
    ],
    "engines": ["google", "bing"],
    "categories": ["general"],
    "safesearch": 1,
    "language": "en"
  }
}
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")
Response Format
{
  "searches": [
    {
      "query": "Brother printers review",
      "results": [
        {
          "title": "Best Brother Printers 2024 Review",
          "link": "https://example.com/review",
          "snippet": "Comprehensive review of Brother printers..."
        }
      ],
      "total_results": 150,
      "success": true
    }
  ],
  "summary": {
    "total_queries": 3,
    "successful_queries": 3,
    "failed_queries": 0
  }
}

Configuration

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

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