SearXNG MCP Server
Provides web search capabilities through SearXNG, enabling searches across multiple search engines with category filtering, language selection, time-based filtering, autocomplete suggestions, and access to instance configuration and health monitoring.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SearXNG MCP Server search for recent developments in quantum computing"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Clone the repository:
git clone https://github.com/martinchen448/searxng-mcp-server.git
cd searxng-mcp-serverInstall the package:
pip install -e .From PyPI (coming soon)
pip install searxng-mcp-serverConfiguration
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 instanceExample:
https://search.example.comorhttp://localhost:8888
SEARXNG_VERIFY_SSL(optional): Whether to verify SSL certificatesDefault:
trueSet to
falsefor 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.batWindows (PowerShell):
.\run-inspector.ps1Linux/macOS:
chmod +x run-inspector.sh
./run-inspector.shOr 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_serverThe 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/searxngSee the SearXNG documentation for more deployment options.
Available Tools
1. search
Perform web searches across multiple search engines.
Parameters:
query(required): Search query stringcategories(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 prefixlanguage(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 monthThe server will use:
{
"query": "northern lights",
"categories": ["images"],
"time_range": "month"
}Example 3: News Search
Ask your MCP client:
Find recent news about artificial intelligenceThe 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 searchimages- Image searchvideos- Video searchnews- News articlesmusic- Music searchfiles- File searchsocial media- Social media postsscience- Scientific articlesit- IT/Programming resourcesmap- 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
pytestCode Formatting
# Format code with black
black src tests
# Lint with ruff
ruff check src tests
# Type checking with mypy
mypy srcProject 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.mdTroubleshooting
Connection Issues
If you encounter connection errors:
Verify the SearXNG URL: Ensure
SEARXNG_BASE_URLis correct and accessibleCheck SSL certificates: For self-signed certificates, set
SEARXNG_VERIFY_SSL=falseTest the instance: Visit the URL in your browser to ensure it's running
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:
Check instance configuration: Use the
get_configtool to see available enginesVerify engines are enabled: Some instances may have limited engines
Try different categories: Some categories may not be available
Check instance logs: Review SearXNG logs for errors
Contributing
Contributions are welcome! Please follow these steps:
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature)Make your changes
Run tests and linting
Commit your changes (
git commit -m 'Add amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE 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 CHANGELOG.md for version history and changes.
Available Tools
4 toolsget_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.
searchA
Search the web using SearXNG search engine.
This tool performs web searches across multiple search engines aggregated by SearXNG. You can filter by categories (general, images, videos, news, etc.), specific engines, language, and time range. Returns comprehensive results including titles, URLs, content snippets, and metadata.
Use this when you need to:
Search for information on the web
Find recent news or articles
Search for images or videos
Get diverse results from multiple search engines
Research a topic across different sources
Inputs: query (required), categories, engines, language, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Unofficial Serper MCP β wraps the Serper Google Search API (serper.dev)
Web search API and MCP server for developers building AI agents.
Unofficial SerpApi MCP β wraps SerpApi (serpapi.com) search engines
One MCP server for all web data. Scrape, search, crawl, and AI research in one install.
Related MCP Servers
- AlicenseBqualityCmaintenanceAn 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.24MIT
- AlicenseNot gradedqualityDmaintenanceAn 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.14MIT
- FlicenseNot gradedqualityDmaintenanceProvides 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.-
- AlicenseAqualityBmaintenanceEnables 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.2554 npmMIT