Skip to main content
Glama
SearXNG MCP Server

SearXNG MCP Server

SearXNG MCP Server

A Model Context Protocol (MCP) server that integrates with SearXNG, providing powerful web search capabilities to MCP clients like Claude Desktop, Cline, and other MCP-compatible applications.

Features

  • πŸ” Web Search: Search across multiple search engines aggregated by SearXNG

  • 🎯 Category Filtering: Filter by categories (general, images, videos, news, etc.)

  • 🌐 Multi-Engine: Query specific search engines or use them all

  • 🌍 Localization: Search in different languages

  • ⏰ Time Filtering: Filter results by time range (day, month, year)

  • πŸ›‘οΈ Safe Search: Configurable safe search levels

  • πŸ’‘ Autocomplete: Get search suggestions for query completion

  • πŸ”§ Configuration Access: Query SearXNG instance capabilities

  • πŸ₯ Health Monitoring: Check instance health status

Related MCP server: SearXNG MCP Server

Prerequisites

  • Python 3.10 or higher

  • A running SearXNG instance (local or remote)

  • An MCP client (e.g., Claude Desktop, Cline)

Installation

From Source

  1. Clone the repository:

git clone https://github.com/martinchen448/searxng-mcp-server.git
cd searxng-mcp-server
  1. Install the package:

pip install -e .

From PyPI (coming soon)

pip install searxng-mcp-server

Configuration

For Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

For Local Instance (Recommended):

{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["-m", "searxng_mcp_server"],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:8080/",
        "SEARXNG_VERIFY_SSL": "false"
      }
    }
  }
}

For Public Instance:

{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["-m", "searxng_mcp_server"],
      "env": {
        "SEARXNG_BASE_URL": "https://searx.be",
        "SEARXNG_VERIFY_SSL": "true"
      }
    }
  }
}

For Cline (VSCode Extension)

Add to your MCP settings file:

Path: <User Directory>/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json

For Local Instance (Recommended):

{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["-m", "searxng_mcp_server"],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:8080/",
        "SEARXNG_VERIFY_SSL": "false"
      }
    }
  }
}

For Public Instance:

{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["-m", "searxng_mcp_server"],
      "env": {
        "SEARXNG_BASE_URL": "https://searx.be",
        "SEARXNG_VERIFY_SSL": "true"
      }
    }
  }
}

Environment Variables

  • SEARXNG_BASE_URL (required): Base URL of your SearXNG instance

    • Example: https://search.example.com or http://localhost:8888

  • SEARXNG_VERIFY_SSL (optional): Whether to verify SSL certificates

    • Default: true

    • Set to false for self-signed certificates or local development

Testing with MCP Inspector

Before using with Claude Desktop or Cline, test your server with the MCP Inspector.

Quick Start

Use the provided convenience scripts:

Windows (Command Prompt):

run-inspector.bat

Windows (PowerShell):

.\run-inspector.ps1

Linux/macOS:

chmod +x run-inspector.sh
./run-inspector.sh

Or run directly:

# Set environment variable first
export SEARXNG_BASE_URL=https://searx.be  # Linux/macOS
set SEARXNG_BASE_URL=https://searx.be     # Windows CMD
$env:SEARXNG_BASE_URL="https://searx.be"  # Windows PowerShell

# Then run inspector
npx @modelcontextprotocol/inspector python -m searxng_mcp_server

The Inspector will open in your browser (typically http://localhost:5173) where you can:

  • Test all tools interactively

  • View real-time request/response logs

  • Inspect resources

  • Debug connection issues

For detailed testing instructions, see Testing with MCP Inspector.

Setting Up SearXNG

If you don't have a SearXNG instance, you can:

Use a Public Instance

Find public instances at: https://searx.space/

Example public instances:

Important Notes:

  • Public instances may have rate limits or restrictions

  • Some public instances block automated requests (HTTP 403 errors)

  • For reliable operation, consider running your own instance

  • If you encounter 403 errors, try a different public instance or set up a local instance

Run Your Own Instance

Using Docker (recommended):

docker pull searxng/searxng
docker run -d -p 8888:8080 \
  -v "${PWD}/searxng:/etc/searxng" \
  -e "BASE_URL=http://localhost:8888/" \
  -e "INSTANCE_NAME=my-instance" \
  searxng/searxng

See the SearXNG documentation for more deployment options.

Available Tools

Perform web searches across multiple search engines.

Parameters:

  • query (required): Search query string

  • categories (optional): Array of categories (e.g., ["general", "images", "news"])

  • engines (optional): Array of specific engines (e.g., ["google", "bing"])

  • language (optional): Language code (default: "en")

  • page (optional): Page number for pagination (default: 1)

  • time_range (optional): Filter by time ("day", "month", "year")

  • safesearch (optional): Safe search level (0=off, 1=moderate, 2=strict)

Example:

{
  "query": "Python async programming",
  "categories": ["general"],
  "language": "en",
  "time_range": "year",
  "safesearch": 0
}

2. get_suggestions

Get autocomplete suggestions for a query prefix.

Parameters:

  • query (required): Query prefix

  • language (optional): Language code (default: "en")

Example:

{
  "query": "machine learn",
  "language": "en"
}

3. health_check

Check if the SearXNG instance is accessible and healthy.

Parameters: None

4. get_config

Get the configuration and capabilities of the SearXNG instance.

Parameters: None

Returns information about:

  • Available search engines

  • Enabled categories

  • Supported languages

  • Active plugins

  • Instance settings

Available Resources

searxng://config

Access to the SearXNG instance configuration as a persistent resource.

searxng://health

Health status of the SearXNG instance as a persistent resource.

Usage Examples

Ask your MCP client:

Search for "best practices for Python async programming"

Ask your MCP client:

Search for images of "northern lights" from the past month

The server will use:

{
  "query": "northern lights",
  "categories": ["images"],
  "time_range": "month"
}

Ask your MCP client:

Find recent news about artificial intelligence

The server will use:

{
  "query": "artificial intelligence",
  "categories": ["news"],
  "time_range": "day"
}

Example 4: Get Search Suggestions

Ask your MCP client:

Get search suggestions for "climate"

Search Categories

Available categories in SearXNG:

  • general - General web search

  • images - Image search

  • videos - Video search

  • news - News articles

  • music - Music search

  • files - File search

  • social media - Social media posts

  • science - Scientific articles

  • it - IT/Programming resources

  • map - Maps and locations

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/martinchen448/searxng-mcp-server.git
cd searxng-mcp-server

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

Running Tests

pytest

Code Formatting

# Format code with black
black src tests

# Lint with ruff
ruff check src tests

# Type checking with mypy
mypy src

Project Structure

searxng-mcp-server/
β”œβ”€β”€ src/
β”‚   └── searxng_mcp_server/
β”‚       β”œβ”€β”€ __init__.py
β”‚       β”œβ”€β”€ server.py      # MCP server implementation
β”‚       └── client.py      # SearXNG API client
β”œβ”€β”€ tests/
β”‚   β”œβ”€β”€ test_server.py
β”‚   └── test_client.py
β”œβ”€β”€ pyproject.toml
└── README.md

Troubleshooting

Connection Issues

If you encounter connection errors:

  1. Verify the SearXNG URL: Ensure SEARXNG_BASE_URL is correct and accessible

  2. Check SSL certificates: For self-signed certificates, set SEARXNG_VERIFY_SSL=false

  3. Test the instance: Visit the URL in your browser to ensure it's running

  4. Check firewall: Ensure no firewall is blocking the connection

SSL Certificate Errors

For self-signed certificates or local development:

{
  "env": {
    "SEARXNG_BASE_URL": "http://localhost:8888",
    "SEARXNG_VERIFY_SSL": "false"
  }
}

No Results

If searches return no results:

  1. Check instance configuration: Use the get_config tool to see available engines

  2. Verify engines are enabled: Some instances may have limited engines

  3. Try different categories: Some categories may not be available

  4. Check instance logs: Review SearXNG logs for errors

Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Make your changes

  4. Run tests and linting

  5. Commit your changes (git commit -m 'Add amazing feature')

  6. Push to the branch (git push origin feature/amazing-feature)

  7. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Support

Changelog

See CHANGELOG.md for version history and changes.

Available Tools

4 tools
get_configA

Get the configuration of the SearXNG instance.

This tool retrieves the SearXNG instance configuration including available search engines, enabled categories, supported locales, plugins, and instance settings. Useful for understanding what capabilities are available.

Use this when you need to:

  • Discover available search engines

  • See what categories are enabled

  • Check supported languages/locales

  • Understand instance capabilities and settings

Inputs: no named parameters.

get_suggestionsA

Get search suggestions/autocomplete for a query prefix.

This tool provides search suggestions based on a partial query, similar to autocomplete functionality in search engines. Useful for discovering related searches or expanding on a topic.

Use this when you need to:

  • Get autocomplete suggestions for a search

  • Discover related search terms

  • Help users formulate better search queries

  • Explore variations of a search topic

Inputs: query (required), language.

health_checkA

Check the health status of the SearXNG instance.

This tool verifies that the SearXNG instance is running and accessible. Useful for diagnostics and ensuring the search service is operational before performing searches.

Use this when you need to:

  • Verify the SearXNG instance is accessible

  • Diagnose connection issues

  • Check service availability before searching

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: get_config retrieves instance configuration, get_suggestions provides autocomplete, health_check verifies service status, and search performs actual web searches. The descriptions reinforce these distinct roles, making misselection unlikely.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case: get_config, get_suggestions, health_check, and search. The naming is predictable and readable throughout the set.

    Tool Count4/5

    Four tools is reasonable for a search server, covering configuration, suggestions, health, and core search functionality. It feels slightly minimal but well-scoped, as each tool serves a clear purpose without redundancy.

    Completeness4/5

    The tool set covers the essential operations for interacting with a SearXNG instance: checking health, retrieving configuration, getting suggestions, and performing searches. A minor gap might be the lack of tools for managing search history or preferences, but core workflows are fully supported.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      An MCP server that integrates with the SearXNG API to provide comprehensive web search capabilities with features like time filtering, language selection, and safe search. It also enables users to fetch and convert web content from specific URLs into markdown format.
      2
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables web search capabilities by integrating with a SearXNG instance to aggregate results from over 130 engines. It allows users to perform filtered searches across categories like news, science, and social media while supporting advanced parameters for language and time range.
      14
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides a free web search tool to MCP clients by connecting to a self-hosted SearXNG metasearch instance, enabling users to search the web with customizable parameters like categories and time range.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP-compatible clients to perform web searches through a self-hosted SearXNG instance, with support for configurable languages, categories, time ranges, and safe search settings.
      2
      554 npm
      MIT