martinchen448/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

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

2. 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 .

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:

• https://searx.be
• https://searx.tiekoetter.com
• https://search.sapti.me

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 file for details.

Acknowledgments

• SearXNG - The privacy-respecting metasearch engine
• Model Context Protocol - The protocol specification
• Anthropic - For developing the MCP standard

Related Projects

• SearXNG - Privacy-respecting metasearch engine
• MCP Specification - MCP protocol documentation
• Claude Desktop - Desktop application with MCP support

Support

• 🐛 Report bugs
• 💡 Request features
• 📖 Documentation

Changelog

See for version history and changes.