SearXNG MCP Server

A Model Context Protocol (MCP) server that provides web search capabilities through SearXNG instances.

Features

• 🔍 Web Search — Query any SearXNG instance for general web results
• 📁 Category-Specific Search — Search images, videos, news, music, science, etc.
• ⚙️ Engine Selection — Use specific search engines (Google, Bing, DuckDuckGo, etc.)
• 🕐 Time Filtering — Filter results by day, week, month, or year
• 📋 Engine Discovery — List all available SearXNG engines

Installation

From PyPI (when published)

pip install searxng-mcp-server

From Source

git clone https://github.com/<username>/searxng-mcp-server.git
cd searxng-mcp-server
pip install -e ".[dev]"

Configuration

Set the following environment variables:

Variable	Description	Default
SEARXNG_URL	SearXNG instance URL	http://localhost:8888 (local Docker)
SEARXNG_ENGINES	Comma-separated engine list	(none — uses all)
SEARXNG_LANG	Search language code	en-US

Example:

export SEARXNG_URL="http://localhost:8888"
export SEARXNG_ENGINES="google,bing,duckduckgo"
export SEARXNG_LANG="zh-TW"

Usage with Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  searxng:
    command: "uv"
    args: ["run", "--directory", "/path/to/searxng-mcp-server", "searxng-mcp"]
    env:
      SEARXNG_URL: "https://search.sapti.me"

Usage with Claude Desktop / Cursor / VS Code

Add to your MCP configuration:

{
  "mcpServers": {
    "searxng": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/searxng-mcp-server", "searxng-mcp"],
      "env": {
        "SEARXNG_URL": "https://search.sapti.me"
      }
    }
  }
}

Available Tools

search_web

Search the web using a SearXNG instance.

Parameters:

• query (string, required): The search query
• max_results (int, optional): Maximum results to return (default: 10)
• time_range (string, optional): Filter by time — 'day', 'week', 'month', 'year'

search_specific

Search using specific categories and/or engines.

Parameters:

• query (string, required): The search query
• categories (list of strings, optional): Categories to search (general, images, videos, news, music, files, it, science, social media)
• engines (list of strings, optional): Specific engines to use
• max_results (int, optional): Maximum results (default: 10)
• time_range (string, optional): Time filter

search_by_category

Search a specific SearXNG category.

Parameters:

• query (string, required): The search query
• category (string, optional): Category to search (default: 'general')
• max_results (int, optional): Maximum results (default: 10)

list_engines

List all available SearXNG search engines from searxng.org.

Parameters: None

Development

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Lint with ruff
ruff check src/ tests/

Public SearXNG Instances

You can use any public or self-hosted SearXNG instance. Some public instances:

• https://search.sapti.me
• https://searx.be
• https://search.ononoki.org

⚠️ Note: Public instances may have rate limits or be unreliable. For production use, consider self-hosting your own SearXNG instance.

License

MIT