SearXNG MCP Server

by tisDDM
Verified

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Integrations

  • Supports configuration via .env files for setting SearXNG URL and optional authentication credentials

  • Provides search results in Markdown format for better readability and structure

  • Enables running as a Node.js-based MCP server that can be integrated with VSCode and other environments

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

  1. Open Claude Desktop
  2. Go to Settings > MCP Servers
  3. 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

  1. Open VSCode
  2. Go to Settings > Extensions > Claude > MCP Settings
  3. 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

ParameterTypeDescriptionDefaultRequired
querystringSearch query-Yes
languagestringLanguage code for search results (e.g., 'en', 'de', 'fr')'en'No
time_rangestringTime range for search results. Options: 'day', 'week', 'month', 'year'nullNo
categoriesarray of stringsCategories to search in (e.g., 'general', 'images', 'news')nullNo
enginesarray of stringsSpecific search engines to usenullNo
safesearchnumberSafe search level: 0 (off), 1 (moderate), 2 (strict)1No
pagenonumberPage number for results. Must be minimum 11No
max_resultsnumberMaximum number of search results to return. Range: 1-5010No

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

-
security - not tested
A
license - permissive license
-
quality - not tested

A Model Context Protocol server that enables AI assistants to perform web searches using SearXNG, a privacy-respecting metasearch engine.

  1. Features
    1. Installation
      1. Prerequisites
      2. Install from source
    2. Configuration
      1. Usage
        1. Running the server
        2. Integrating with Claude Desktop
        3. Integrating with Claude in VSCode
      2. Usage with Smolagents
        1. Available Tools
          1. searxngsearch
        2. Development
          1. Setup
          2. Build
          3. Watch mode (for development)
          4. Testing with MCP Inspector
        3. License