SearXNG MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to perform web searches using SearXNG, a privacy-respecting metasearch engine. Works out-of-the-box with zero additional deployment by automatically selecting a random instance from SearX.space, while also supporting private instances with basic authentication.

Features

Zero-configuration setup: Works immediately by using a random public instance from SearX.space
Private instance support: Connect to your own SearXNG instance with optional basic authentication
Perform web searches with customizable parameters
Support for multiple search engines
Privacy-focused search results
Markdown-formatted search results
Sensible default values for all parameters

CAVEAT - Public Instances might be unavailabe for this purpose and return "Request failed with status code 429"

Installation

Prerequisites

Node.js (v16 or higher)
npm (v7 or higher)
Access to a SearXNG instance (self-hosted or public)

Install from source

# Clone the repository
git clone https://github.com/tisDDM/searxng-mcp.git
cd searxng-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

The SearXNG MCP server can be configured with the following environment variables:

SEARXNG_URL (optional): The URL of your SearXNG instance (e.g., https://searx.example.com). If not provided, a random public instance from SearX.space will be automatically selected, making the server usable with zero additional deployment.
USE_RANDOM_INSTANCE (optional): Set to "false" to disable random instance selection when no URL is provided. Default is "true".
SEARXNG_USERNAME (optional): Username for basic authentication when connecting to a private instance
SEARXNG_PASSWORD (optional): Password for basic authentication when connecting to a private instance

You can set these environment variables in a .env file in the root directory of the project:

SEARXNG_URL=https://searx.example.com
SEARXNG_USERNAME=your_username
SEARXNG_PASSWORD=your_password

Usage

Running the server

# If installed globally
searxngmcp

# If installed from source
node build/index.js

Integrating with Claude Desktop

Open Claude Desktop
Go to Settings > MCP Servers

Add a new MCP server with the following configuration:

{
  "mcpServers": {
    "searxngmcp": {
      "command": "searxngmcp",
      "env": {
        // Optional: If not provided, a random public instance will be used
        "SEARXNG_URL": "https://searx.example.com",
        // Optional: Only needed for private instances with authentication
        "SEARXNG_USERNAME": "your_username",
        "SEARXNG_PASSWORD": "your_password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Integrating with Claude in VSCode

Open VSCode
Go to Settings > Extensions > Claude > MCP Settings

Add a new MCP server with the following configuration:

{
  "mcpServers": {
    "searxngmcp": {
      "command": "node",
      "args": ["/path/to/searxng-mcp/build/index.js"],
      "env": {
        // Optional: If not provided, a random public instance will be used
        "SEARXNG_URL": "https://searx.example.com",
        // Optional: Only needed for private instances with authentication
        "SEARXNG_USERNAME": "your_username",
        "SEARXNG_PASSWORD": "your_password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Usage with Smolagents

SearXNG MCP can be easily integrated with Smolagents, a lightweight framework for building AI agents. This allows you to create powerful research agents that can search the web and process the results:

from smolagents import CodeAgent, LiteLLMModel, ToolCollection
from mcp import StdioServerParameters

# Configure the SearXNG MCP server
server_parameters = StdioServerParameters(
    command="node",
    args=["path/to/searxng-mcp/build/index.js"],
    env={
        "SEARXNG_URL": "https://your-searxng-instance.com",
        "SEARXNG_USERNAME": "your_username",  # Optional
        "SEARXNG_PASSWORD": "your_password"   # Optional
    }
)

# Create a tool collection from the MCP server
with ToolCollection.from_mcp(server_parameters) as tool_collection:
    # Initialize your LLM model
    model = LiteLLMModel(
        model_id="your-model-id",
        api_key="your-api-key",
        temperature=0.7
    )
    
    # Create an agent with the search tools
    search_agent = CodeAgent(
        name="search_agent",
        tools=tool_collection.tools,
        model=model
    )
    
    # Run the agent with a search prompt
    result = search_agent.run(
        "Perform a search about: 'climate change solutions' and summarize the top 5 results."
    )
    
    print(result)

Available Tools

searxngsearch

Perform web searches using SearXNG, a privacy-respecting metasearch engine. Returns relevant web content with customizable parameters.

Parameters

Parameter	Type	Description	Default	Required
query	string	Search query	-	Yes
language	string	Language code for search results (e.g., 'en', 'de', 'fr')	'en'	No
time_range	string	Time range for search results. Options: 'day', 'week', 'month', 'year'	null	No
categories	array of strings	Categories to search in (e.g., 'general', 'images', 'news')	null	No
engines	array of strings	Specific search engines to use	null	No
safesearch	number	Safe search level: 0 (off), 1 (moderate), 2 (strict)	1	No
pageno	number	Page number for results. Must be minimum 1	1	No
max_results	number	Maximum number of search results to return. Range: 1-50	10	No

Example

// Example request
const result = await client.callTool('searxngsearch', {
  query: 'climate change solutions',
  language: 'en',
  time_range: 'year',
  categories: ['general', 'news'],
  safesearch: 1,
  max_results: 5
});

Development

Setup

# Clone the repository
git clone https://github.com/tisDDM/searxng-mcp.git
cd searxng-mcp

# Install dependencies
npm install

Build

npm run build

Watch mode (for development)

npm run watch

Testing with MCP Inspector

npm run inspector

License

MIT

SearXNG 搜索