SearXNG MCP Server: Web Search Integration for AI Assistants

The SearXNG MCP Server is a Model Context Protocol (MCP) implementation that enables AI assistants to perform web searches using SearXNG, a privacy-respecting metasearch engine. It 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 unavailable 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.
• 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.

Example .env file:

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 integrated with Smolagents, a lightweight framework for building AI agents:

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. Returns relevant web content with customizable parameters.

Parameters

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 License

About

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

Resources

Readme

License

MIT License