Skip to main content
Glama

SearXNG MCP Server

by martinchen448
GitHub
Python
MIT License
  • Linux
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

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

1. search

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

Example 1: Basic Web Search

Ask your MCP client:

Search for "best practices for Python async programming"

Example 2: Image Search

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

Example 3: News Search

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

Related Projects

Support

Changelog

See CHANGELOG.md for version history and changes.

Deploy Server
A
security ā€“ no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

Integrates with SearXNG metasearch engine to provide powerful web search capabilities across multiple search engines with filtering options for categories, languages, time ranges, and safe search levels. Enables comprehensive web searches, autocomplete suggestions, and search engine configuration access through MCP-compatible applications.

  1. Features
    1. Prerequisites
      1. Installation
        1. From Source
        2. From PyPI (coming soon)
      2. Configuration
        1. For Claude Desktop
        2. For Cline (VSCode Extension)
        3. Environment Variables
      3. Testing with MCP Inspector
        1. Quick Start
      4. Setting Up SearXNG
        1. Use a Public Instance
        2. Run Your Own Instance
      5. Available Tools
        1. 1. search
        2. 2. get_suggestions
        3. 3. health_check
        4. 4. get_config
      6. Available Resources
        1. searxng://config
        2. searxng://health
      7. Usage Examples
        1. Example 1: Basic Web Search
        2. Example 2: Image Search
        3. Example 3: News Search
        4. Example 4: Get Search Suggestions
      8. Search Categories
        1. Development
          1. Setup Development Environment
          2. Running Tests
          3. Code Formatting
          4. Project Structure
        2. Troubleshooting
          1. Connection Issues
          2. SSL Certificate Errors
          3. No Results
        3. Contributing
          1. License
            1. Acknowledgments
              1. Related Projects
                1. Support
                  1. Changelog

                    New MCP Servers

                    MCP directory API

                    We provide all the information about MCP servers via our MCP API.

                    curl -X GET 'https://glama.ai/api/mcp/v1/servers/martinchen448/searxng-mcp-server'

                    If you have feedback or need assistance with the MCP directory API, please join our Discord server