SearXNG

A Model Context Protocol Server for SearXNG

GitHub

SearXNG MCP Server

An MCP server implementation that integrates the SearXNG API, providing web search capabilities.

Features

Web Search: General queries, news, articles, with pagination.
URL Content Reading: Advanced content extraction with pagination, section filtering, and heading extraction.
Intelligent Caching: URL content is cached with TTL (Time-To-Live) to improve performance and reduce redundant requests.
Pagination: Control which page of results to retrieve.
Time Filtering: Filter results by time range (day, month, year).
Language Selection: Filter results by preferred language.
Safe Search: Control content filtering level for search results.

Tools

searxng_web_search
- Execute web searches with pagination
- Inputs:
  - query (string): The search query. This string is passed to external search services.
  - pageno (number, optional): Search page number, starts at 1 (default 1)
  - time_range (string, optional): Filter results by time range - one of: "day", "month", "year" (default: none)
  - language (string, optional): Language code for results (e.g., "en", "fr", "de") or "all" (default: "all")
  - safesearch (number, optional): Safe search filter level (0: None, 1: Moderate, 2: Strict) (default: instance setting)
web_url_read
- Read and convert the content from a URL to markdown with advanced content extraction options
- Inputs:
  - url (string): The URL to fetch and process
  - startChar (number, optional): Starting character position for content extraction (default: 0)
  - maxLength (number, optional): Maximum number of characters to return
  - section (string, optional): Extract content under a specific heading (searches for heading text)
  - paragraphRange (string, optional): Return specific paragraph ranges (e.g., '1-5', '3', '10-')
  - readHeadings (boolean, optional): Return only a list of headings instead of full content

Configuration

Environment Variables

Required

SEARXNG_URL: SearXNG instance URL (default: http://localhost:8080)
- Format: <protocol>://<hostname>[:<port>]
- Example: https://search.example.com

Optional

AUTH_USERNAME / AUTH_PASSWORD: HTTP Basic Auth credentials for searxng_web_search (password-protected SearXNG instances)
USER_AGENT: Global default User-Agent header used by both searxng_web_search and web_url_read (e.g., MyBot/1.0)
URL_READER_USER_AGENT: Custom User-Agent specifically for the web_url_read tool (overrides USER_AGENT for URL reading requests)
HTTP_PROXY / HTTPS_PROXY: Global proxy URLs for routing traffic (fallback for both interfaces)
- Format: http://[username:password@]proxy.host:port
NO_PROXY: Comma-separated bypass list (e.g., localhost,.internal,example.com)

Interface-Specific Proxies (Optional)

SEARCH_HTTP_PROXY / SEARCH_HTTPS_PROXY: Proxy for searxng_web_search tool only
URL_READER_HTTP_PROXY / URL_READER_HTTPS_PROXY: Proxy for web_url_read tool only
- These take priority over HTTP_PROXY/HTTPS_PROXY for their respective interfaces

Advanced Configuration

# Separate proxies for search and URL reading
SEARCH_HTTP_PROXY=http://search-proxy:8080
URL_READER_HTTP_PROXY=http://reader-proxy:8080

# Custom user_agent for URL reader
URL_READER_USER_AGENT="Mozilla/5.0 (compatible; Bot/1.0)"

Installation & Configuration

NPX

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Full Configuration Example (All Options)

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "AUTH_USERNAME": "your_username",
        "AUTH_PASSWORD": "your_password",
        "USER_AGENT": "MyBot/1.0",
        "URL_READER_USER_AGENT": "Mozilla/5.0 (compatible; MyBot/1.0)",
        "SEARCH_HTTP_PROXY": "http://search-proxy.company.com:8080",
        "URL_READER_HTTP_PROXY": "http://reader-proxy.company.com:8080",
        "HTTP_PROXY": "http://global-proxy.company.com:8080",
        "HTTPS_PROXY": "http://global-proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
      }
    }
  }
}

Note: Mix and match environment variables as needed. All optional variables can be used independently or together.

NPM

npm install -g mcp-searxng

{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Full Configuration Example (All Options)

{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "AUTH_USERNAME": "your_username",
        "AUTH_PASSWORD": "your_password",
        "USER_AGENT": "MyBot/1.0",
        "URL_READER_USER_AGENT": "Mozilla/5.0 (compatible; MyBot/1.0)",
        "SEARCH_HTTP_PROXY": "http://search-proxy.company.com:8080",
        "URL_READER_HTTP_PROXY": "http://reader-proxy.company.com:8080",
        "HTTP_PROXY": "http://global-proxy.company.com:8080",
        "HTTPS_PROXY": "http://global-proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
      }
    }
  }
}

Docker

Using Pre-built Image from Docker Hub

docker pull isokoliuk/mcp-searxng:latest

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEARXNG_URL",
        "isokoliuk/mcp-searxng:latest"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Full Configuration Example (All Options)

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEARXNG_URL",
        "-e", "AUTH_USERNAME",
        "-e", "AUTH_PASSWORD",
        "-e", "USER_AGENT",
        "-e", "URL_READER_USER_AGENT",
        "-e", "SEARCH_HTTP_PROXY",
        "-e", "SEARCH_HTTPS_PROXY",
        "-e", "URL_READER_HTTP_PROXY",
        "-e", "URL_READER_HTTPS_PROXY",
        "-e", "HTTP_PROXY",
        "-e", "HTTPS_PROXY",
        "-e", "NO_PROXY",
        "isokoliuk/mcp-searxng:latest"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "AUTH_USERNAME": "your_username",
        "AUTH_PASSWORD": "your_password",
        "USER_AGENT": "MyBot/1.0",
        "URL_READER_USER_AGENT": "Mozilla/5.0 (compatible; MyBot/1.0)",
        "SEARCH_HTTP_PROXY": "http://search-proxy.company.com:8080",
        "URL_READER_HTTP_PROXY": "http://reader-proxy.company.com:8080",
        "HTTP_PROXY": "http://global-proxy.company.com:8080",
        "HTTPS_PROXY": "http://global-proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
      }
    }
  }
}

Note: Add only the -e flags and env variables you need.

Build Locally

docker build -t mcp-searxng:latest -f Dockerfile .

Use the same configuration as above, replacing isokoliuk/mcp-searxng:latest with mcp-searxng:latest.

Docker Compose

Create a docker-compose.yml file:

services:
  mcp-searxng:
    image: isokoliuk/mcp-searxng:latest
    stdin_open: true
    environment:
      - SEARXNG_URL=YOUR_SEARXNG_INSTANCE_URL
      # Add any optional variables as needed:
      # - AUTH_USERNAME=your_username
      # - AUTH_PASSWORD=your_password
      # - USER_AGENT=MyBot/1.0
      # - URL_READER_USER_AGENT=Mozilla/5.0 (compatible; MyBot/1.0)
      # - SEARCH_HTTP_PROXY=http://search-proxy.company.com:8080
      # - URL_READER_HTTP_PROXY=http://reader-proxy.company.com:8080
      # - HTTP_PROXY=http://global-proxy.company.com:8080
      # - HTTPS_PROXY=http://proxy.company.com:8080
      # - NO_PROXY=localhost,127.0.0.1,.local,.internal

Then configure your MCP client:

{
  "mcpServers": {
    "searxng": {
      "command": "docker-compose",
      "args": ["run", "--rm", "mcp-searxng"]
    }
  }
}

HTTP Transport (Optional)

The server supports both STDIO (default) and HTTP transports. Set MCP_HTTP_PORT to enable HTTP mode.

{
  "mcpServers": {
    "searxng-http": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "MCP_HTTP_PORT": "3000"
      }
    }
  }
}

HTTP Endpoints:

MCP Protocol: POST/GET/DELETE /mcp
Health Check: GET /health

Testing:

MCP_HTTP_PORT=3000 SEARXNG_URL=http://localhost:8080 mcp-searxng
curl http://localhost:3000/health

Running evals

SEARXNG_URL=YOUR_URL OPENAI_API_KEY=your-key npx mcp-eval evals.ts src/index.ts

For Developers

Contributing

We welcome contributions! Follow these guidelines:

Coding Standards:

Use TypeScript with strict type safety
Follow existing error handling patterns
Write concise, informative error messages
Include unit tests for new functionality
Maintain 90%+ test coverage
Test with MCP inspector before submitting
Run evals to verify functionality

Workflow:

Fork and clone:

git clone https://github.com/YOUR_USERNAME/mcp-searxng.git
cd mcp-searxng
git remote add upstream https://github.com/ihor-sokoliuk/mcp-searxng.git

Setup:

npm install
npm run watch  # Development mode with file watching

Development:

git checkout -b feature/your-feature-name
# Make changes in src/
npm run build
npm test
npm run test:coverage
npm run inspector

Submit:

git commit -m "feat: description"
git push origin feature/your-feature-name
# Create PR on GitHub

Testing

npm test                    # Run all tests
npm run test:coverage      # Generate coverage report
npm run test:watch         # Watch mode

Coverage: 100% success rate with comprehensive unit tests covering error handling, types, proxy configs, resources, and logging.

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

Serveurs connexes

Azure AI Agent & Search

Search content using Azure AI Agent Service and Azure AI Search.

MCP Lucene Server

MCP Lucene Server is a Model Context Protocol (MCP) server that exposes Apache Lucene's full-text search capabilities through a conversational interface. It allows AI assistants (like Claude) to help users search, index, and manage document collections without requiring technical knowledge of Lucene or search engines.

Tavily Search

AI-powered web search using the Tavily Search API.

PBS API

Access Australian Pharmaceutical Benefits Scheme data for medicine information, pricing, and availability. Built with Python and FastAPI.

Geocoding Tool

Convert city names and locations into latitude and longitude coordinates using the free OpenStreetMap Nominatim API. No API key is required.

DeepResearch

Lightning-Fast, High-Accuracy Deep Research Agent 👉 8–10x faster 👉 Greater depth & accuracy 👉 Unlimited parallel runs

HyperKitty MCP Server

MCP server that provides read-only access to HyperKitty, the web-based email archive component of Mailman 3.

SearxNG MCP Server

Provides web search capabilities using a self-hosted SearxNG instance, allowing AI assistants to search the web.

SearXNG MCP Server

A privacy-respecting web search server for AI agents, powered by the SearXNG metasearch engine.

FastDomainCheck

Check domain name registration status in bulk using WHOIS and DNS dual verification.