SearXNG MCP Server

# SearXNG MCP Server A Model Context Protocol (MCP) server that integrates with [SearXNG](https://github.com/searxng/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: ```bash git clone https://github.com/martinchen448/searxng-mcp-server.git cd searxng-mcp-server ``` 2. Install the package: ```bash pip install -e . ``` ### From PyPI (coming soon) ```bash 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):** ```json { "mcpServers": { "searxng": { "command": "python", "args": ["-m", "searxng_mcp_server"], "env": { "SEARXNG_BASE_URL": "http://localhost:8080/", "SEARXNG_VERIFY_SSL": "false" } } } } ``` **For Public Instance:** ```json { "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):** ```json { "mcpServers": { "searxng": { "command": "python", "args": ["-m", "searxng_mcp_server"], "env": { "SEARXNG_BASE_URL": "http://localhost:8080/", "SEARXNG_VERIFY_SSL": "false" } } } } ``` **For Public Instance:** ```json { "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):** ```cmd run-inspector.bat ``` **Windows (PowerShell):** ```powershell .\run-inspector.ps1 ``` **Linux/macOS:** ```bash chmod +x run-inspector.sh ./run-inspector.sh ``` **Or run directly:** ```bash # 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](docs/TESTING_WITH_INSPECTOR.md). ## 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): ```bash 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](https://docs.searxng.org/) 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:** ```json { "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:** ```json { "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: ```json { "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: ```json { "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 ```bash # 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 ```bash pytest ``` ### Code Formatting ```bash # 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: ```json { "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](LICENSE) file for details. ## Acknowledgments - [SearXNG](https://github.com/searxng/searxng) - The privacy-respecting metasearch engine - [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification - [Anthropic](https://www.anthropic.com/) - For developing the MCP standard ## Related Projects - [SearXNG](https://github.com/searxng/searxng) - Privacy-respecting metasearch engine - [MCP Specification](https://github.com/modelcontextprotocol/specification) - MCP protocol documentation - [Claude Desktop](https://claude.ai/download) - Desktop application with MCP support ## Support - 🐛 [Report bugs](https://github.com/martinchen448/searxng-mcp-server/issues) - 💡 [Request features](https://github.com/martinchen448/searxng-mcp-server/issues) - 📖 [Documentation](https://github.com/martinchen448/searxng-mcp-server/wiki) ## Changelog See [CHANGELOG.md](CHANGELOG.md) for version history and changes.