Skip to main content
Glama

SearXNG MCP Server

by martinchen448
OverviewInspectNewSchemaRelated ServersScore
Python
Hybrid
MIT License
  • Linux
  • Apple

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?

Related Resources

Tools

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