🔍 SearXNG MCP Server

✨ Overview

SearXNG MCP Server bridges your self-hosted SearXNG instance with AI models using the Model Context Protocol (MCP). It provides a straightforward way for AI agents to perform web searches via your configured SearXNG meta-search engine, enabling them to access up-to-date information from the web.

This server focuses on providing a dead-simple search interface, intentionally limiting the parameters controllable by the AI.

TLDR: This MCP server is published to the npm registry as searxng-mcp. Start using it with your familiar LLM tools via npx or bunx, specifying the SEARXNG_SERVER_URL environment variable with your SearXNG instance URL to start playing.

🤔 Design Philosophy: Simplicity

This MCP server provides a very basic search tool on purpose. You can only provide search keywords and an optional page number.

What you cannot control via this MCP tool:

• Specific search engines to use within SearXNG
• Search categories (e.g., images, news, files)
• Time range filters

Why this limitation?

Many AI/LLMs struggle to correctly utilize complex search parameters. They might:

• Randomly pick inappropriate search engines for a query.
• Attempt to search specialized repositories (like GitHub or arXiv) for general news or software release notes inappropriately.
• Apply time filters that yield no results.

Constantly instructing the AI on how to use complex search filters ("use engine X and Y, not Z", "search in the 'news' category", "only look for results from the last week") is often inefficient and unreliable.

This MCP server avoids that complexity by design. It focuses on the core task: searching the web based on keywords.

How to customize search behavior:

Control which search engines are enabled, default search settings, language preferences, and other advanced features directly within your SearXNG instance configuration. By pre-configuring SearXNG according to your needs, you ensure the AI uses a reliable and pre-vetted search setup without needing complex instructions for each query.

🤖 Model Support

You can use any AI model that supports function calling/tool use and is integrated with an MCP-compatible client. The following model families have been tested with MCP in general (though specific client support may vary):

• Claude 3.x Series
• Gemini 2.0 and newer
• GPT-4.1 Series
• Mistral Large
• Grok
• DeepSeek

💻 Works With

• Claude Desktop
• Open WebUI (via mcpo)
• TypingMind
• Cline / Roo Code
• Cherry Studio

⚙️ Configuration

Before you get started

There is one thing you have to confirm before starting use: Your SearXNG instance must have JSON format enabled, which is disabled by default in most publicly accessible instances.

You can enable it by setting the following options in your SearXNG config:

search:
  formats:
    - html
    - json

Note: You should protect your SearXNG instance from being accessed by unauthorized persons or bots, or it might be abused by automated programs which could cause your IP address to be blocked by search engines.

It is recommended to make it private or whitelisted with IP addresses.

Environment variables

• SEARXNG_SERVER_URL: The base URL to your running SearXNG instance. (Required)
• SEARXNG_MODE: Response engine, json or html. Defaults to json. (Optional)
• SEARXNG_METHOD: HTTP method, get or post. Defaults to get. (Optional)

Example:

SEARXNG_SERVER_URL="https://my-searxng.example.com"
SEARXNG_MODE="json"
SEARXNG_METHOD="get"

Usually, you would configure this in the places where you configure your MCP servers, like the one shown below.

Configure for Claude Desktop

Add this snippet to claude_desktop_config.json:

{
  "mcpServers": {
    "searxng-search": {
      "command": "npx",
      "args": ["-y", "searxng-mcp"],
      "env": {
        "SEARXNG_SERVER_URL": "https://my-searxng.example.com",
        "SEARXNG_MODE": "json",
        "SEARXNG_METHOD": "get"
      }
    }
  }
}

Note: For software that supports MCP they share the same configuration formats. Reference the, consult their documentation, or configure via GUI.

🔧 Available MCP Tools

This server provides one MCP tool:

search_web

• Description: Searches the web using the configured SearXNG meta search engine.
• Input Schema:
  • query (string, required): Search keywords.
  • page (number, optional, default: 1): Page number for pagination
• Output: An array of search result items or an error message.

📝 Data Structure

Input (SearchWebInput)

Corresponds to the search_web tool's input schema defined in src/mcp/schemas.ts.

export const SearchWebInputSchema = z.object({
  query: z
    .string()
    .describe(
      "Search keywords. Use effective and professional search keywords, consider fewer words and time irrelevance to get more results.",
    ),
  page: z
    .optional(z.number().min(1).default(1))
    .describe("Page number for pagination"),
});

Output (SearchResultItem[])

The tool returns an array of objects matching the SearchResultItemSchema defined in src/mcp/schemas.ts.

export const SearchResultItemSchema = z.object({
  url: z.string().url().describe("URL of the search result"),
  title: z.string().describe("Title of the search result"),
  content: z.string().describe("Content snippet of the search result"),
  engines: z
    .array(z.string())
    .describe("List of engines where this result appeared"),
});

📜 License

This project is licensed under the GNU General Public License, version 2.