searxng-mcp

SearXNG MCP Server

A Model Context Protocol (MCP) server that provides privacy-focused web search capabilities through SearXNG, using Streamable HTTP transport.

Features

• Privacy-Focused Search: Leverages SearXNG for anonymous, tracker-free web searches
• Streamable HTTP Transport: Modern HTTP-based MCP protocol for remote access
• Environment Variables: All configuration via environment variables
• HTTP Basic Auth: Support for authentication-protected SearXNG instances
• Advanced Search Parameters: Support for categories, language filters, and time ranges
• Async Architecture: Built with async/await for non-blocking operations

Installation

# Clone the repository
git clone <repo-url>
cd searxng-mcp

# Install dependencies
pip install -e .

# Or using uv
uv pip install -e .

Configuration

All configuration is done via environment variables:

| Variable | Description | Default | |----------|-------------|---------| | SEARXNG_BASE_URL | Base URL of your SearXNG instance | http://127.0.0.1:8888 | | SEARXNG_USERNAME | Username for HTTP Basic Auth (optional) | - | | SEARXNG_PASSWORD | Password for HTTP Basic Auth (optional) | - | | SEARXNG_TIMEOUT | Request timeout in seconds | 10 | | MAX_RESULTS_LIMIT | Maximum results allowed per query | 50 | | HOST | Server host address | 0.0.0.0 | | PORT | Server port | 3000 | | BASE_URL | Base URL path for the MCP server | /searxng-mcp | | LOG_LEVEL | Logging verbosity | INFO |

Using Environment File

Create a searxng.env file from the example:

cp searxng.env.example searxng.env

Edit searxng.env with your settings:

# SearXNG Configuration
SEARXNG_BASE_URL=https://example.com/searxng
SEARXNG_USERNAME=your_username
SEARXNG_PASSWORD=your_password
SEARXNG_TIMEOUT=10
MAX_RESULTS_LIMIT=50

# Server Configuration
HOST=0.0.0.0
PORT=3000
BASE_URL=/searxng-mcp

# Logging
LOG_LEVEL=INFO

Running

Using Python (with env file)

# Load from searxng.env file and run
export $(grep -v '^#' searxng.env | xargs) && python -m searxng_mcp

Using CLI

# With environment variables inline
SEARXNG_BASE_URL=https://example.com/searxng \
SEARXNG_USERNAME=your_username \
SEARXNG_PASSWORD=your_password \
searxng-mcp

Using Docker

Build the image:

docker build -t searxng-mcp .

Run with environment file:

docker run -d \
  --name searxng-mcp \
  --env-file searxng.env \
  -p 127.0.0.1:3000:3000 \
  searxng-mcp

Run with inline environment variables:

docker run -d \
  --name searxng-mcp \
  -e SEARXNG_BASE_URL=https://example.com/searxng \
  -e SEARXNG_USERNAME=your_username \
  -e SEARXNG_PASSWORD=your_password \
  -e HOST=0.0.0.0 \
  -e PORT=3000 \
  -p 127.0.0.1:3000:3000 \
  searxng-mcp

SearXNG Instance

You need a running SearXNG instance. Options:

• Local: docker run -d --name searxng -p 8888:8080 searxng/searxng:latest
• Remote: Use any public or private SearXNG instance

If your SearXNG instance is protected with HTTP Basic Auth, set SEARXNG_USERNAME and SEARXNG_PASSWORD.

MCP Client Configuration

Configure your MCP client to connect to this server:

{
  "mcpServers": {
    "searxng": {
      "type": "streamable-http",
      "url": "http://localhost:3000"
    }
  }
}

If using a reverse proxy:

{
  "mcpServers": {
    "searxng": {
      "type": "streamable-http",
      "url": "http://your-server/searxng-mcp"
    }
  }
}

Usage

Once connected, use the web_search tool:

Basic Search

Search for "Python async programming tutorials"

Search with Maximum Results

Search for "machine learning news" with max_results=20

Category-Specific Search

Available categories:

• general - General web search
• news - News articles
• images - Image search
• videos - Video content
• files - File downloads
• science - Scientific papers and resources
• it - IT and tech resources

Language-Specific Search

Use ISO 639-1 language codes: en, de, fr, es, zh, ja, etc.

Time-Range Filtered Search

Available time ranges: day, week, month, year

Using with Reverse Proxy

For production deployment with a custom base URL, use a reverse proxy:

Nginx Example

location /searxng-mcp/ {
    proxy_pass http://127.0.0.1:3000/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

License

MIT License