article

README

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-mcp