Skip to main content
Glama
kassol

mcp-searxng

by kassol
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

SearXNG MCP Server

An MCP server that integrates the SearXNG API, giving AI assistants web search capabilities.

This fork is published as @kassol/mcp-searxng and includes support for custom outgoing headers via SEARXNG_HEADERS, URL_READER_HEADERS, and their base64 variants.

npm version npm downloads license GitHub repo

Quick Start

Add to your MCP client configuration (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "@kassol/mcp-searxng"],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Replace YOUR_SEARXNG_INSTANCE_URL with the URL of your SearXNG instance (e.g. https://search.example.com).

Related MCP server: SearXNG MCP Server

Features

  • Web Search: General queries, news, articles, with pagination.

  • URL Content Reading: Advanced content extraction with pagination, section filtering, and heading extraction.

  • Intelligent Caching: URL content is cached with TTL (Time-To-Live) to improve performance and reduce redundant requests.

  • Pagination: Control which page of results to retrieve.

  • Time Filtering: Filter results by time range (day, month, year).

  • Language Selection: Filter results by preferred language.

  • Safe Search: Control content filtering level for search results.

How It Works

mcp-searxng is a standalone MCP server — a separate Node.js process that your AI assistant connects to for web search. It queries any SearXNG instance via its HTTP JSON API.

Not a SearXNG plugin: This project cannot be installed as a native SearXNG plugin. Point it at any existing SearXNG instance by setting SEARXNG_URL.

AI Assistant (e.g. Claude)
        │  MCP protocol
        ▼
  mcp-searxng  (this project — Node.js process)
        │  HTTP JSON API  (SEARXNG_URL)
        ▼
  SearXNG instance

Tools

  • searxng_web_search

    • Execute web searches with pagination

    • Inputs:

      • query (string): The search query. This string is passed to external search services.

      • pageno (number, optional): Search page number, starts at 1 (default 1)

      • time_range (string, optional): Filter results by time range - one of: "day", "month", "year" (default: none)

      • language (string, optional): Language code for results (e.g., "en", "fr", "de") or "all" (default: "all")

      • safesearch (number, optional): Safe search filter level (0: None, 1: Moderate, 2: Strict) (default: instance setting)

  • web_url_read

    • Read and convert the content from a URL to markdown with advanced content extraction options

    • Inputs:

      • url (string): The URL to fetch and process

      • startChar (number, optional): Starting character position for content extraction (default: 0)

      • maxLength (number, optional): Maximum number of characters to return

      • section (string, optional): Extract content under a specific heading (searches for heading text)

      • paragraphRange (string, optional): Return specific paragraph ranges (e.g., '1-5', '3', '10-')

      • readHeadings (boolean, optional): Return only a list of headings instead of full content

Installation

npm install -g @kassol/mcp-searxng
{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}
docker build -t mcp-searxng:latest -f Dockerfile .
{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEARXNG_URL",
        "mcp-searxng:latest"
      ],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

To pass additional env vars, add -e VAR_NAME to args and the variable to env.

docker-compose.yml:

services:
  mcp-searxng:
    build:
      context: .
      dockerfile: Dockerfile
    image: mcp-searxng:latest
    stdin_open: true
    environment:
      - SEARXNG_URL=YOUR_SEARXNG_INSTANCE_URL
      # Add optional variables as needed — see CONFIGURATION.md

MCP client config:

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": ["compose", "run", "--rm", "mcp-searxng"]
    }
  }
}

By default the server uses STDIO. Set MCP_HTTP_PORT to enable HTTP mode:

{
  "mcpServers": {
    "searxng-http": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
        "MCP_HTTP_PORT": "3000"
      }
    }
  }
}

Endpoints: POST/GET/DELETE /mcp (MCP protocol), GET /health (health check)

Test it:

MCP_HTTP_PORT=3000 SEARXNG_URL=http://localhost:8080 mcp-searxng
curl http://localhost:3000/health

Configuration

Set SEARXNG_URL to your SearXNG instance URL. All other variables are optional.

Protected SearXNG instances can receive extra search request headers through SEARXNG_HEADERS_BASE64. This is the recommended format for ChatWise and other MCP clients that treat environment variables as plain key-value fields.

Generate the value directly from existing Cloudflare Access environment variables:

export CF_ACCESS_CLIENT_ID='your-client-id.access'
export CF_ACCESS_CLIENT_SECRET='your-client-secret'

node -e 'console.log(Buffer.from(JSON.stringify({"CF-Access-Client-Id":process.env.CF_ACCESS_CLIENT_ID,"CF-Access-Client-Secret":process.env.CF_ACCESS_CLIENT_SECRET})).toString("base64"))'

Verify the generated value:

export SEARXNG_HEADERS_BASE64='paste-generated-value-here'
node -e 'console.log(Buffer.from(process.env.SEARXNG_HEADERS_BASE64,"base64").toString("utf8"))'

MCP client configuration:

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "@kassol/mcp-searxng"],
      "env": {
        "SEARXNG_URL": "https://search.example.com",
        "SEARXNG_HEADERS_BASE64": "eyJDRi1BY2Nlc3MtQ2xpZW50LUlkIjoieW91ci1jbGllbnQtaWQuYWNjZXNzIiwiQ0YtQWNjZXNzLUNsaWVudC1TZWNyZXQiOiJ5b3VyLWNsaWVudC1zZWNyZXQifQ=="
      }
    }
  }
}

ChatWise environment variables:

SEARXNG_URL=https://search.example.com
USER_AGENT=Mozilla/5.0
SEARXNG_HEADERS_BASE64=paste-generated-value-here

SEARXNG_HEADERS_BASE64 applies only to searxng_web_search requests. Use URL_READER_HEADERS_BASE64 for headers that should be sent by web_url_read.

Full environment variable reference: CONFIGURATION.md

Troubleshooting

403 Forbidden from SearXNG

Your SearXNG instance likely has JSON format disabled. Edit settings.yml (usually /etc/searxng/settings.yml):

search:
  formats:
    - html
    - json

Restart SearXNG (docker restart searxng) then verify:

curl 'http://localhost:8080/search?q=test&format=json'

You should receive a JSON response. If not, confirm the file is correctly mounted and YAML indentation is valid.

See also: SearXNG settings docs · discussion

Contributing

See CONTRIBUTING.md

License

MIT — see LICENSE for details.

Available Tools

2 tools
web_url_readA
Read-only

Read the content from an URL. Use this for further information retrieving to understand the content of each URL.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesURL
sectionNoExtract content under a specific heading (searches for heading text)
maxLengthNoMaximum number of characters to return
startCharNoStarting character position for content extraction (default: 0)
readHeadingsNoReturn only a list of headings instead of full content
paragraphRangeNoReturn specific paragraph ranges (e.g., '1-5', '3', '10-')

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description states a read operation, consistent with the readOnlyHint annotation, and adds that it returns content from a URL. However, it provides no additional behavioral details beyond what annotations already imply, such as output format or handling of dynamic content.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded with the core purpose. The second sentence is somewhat redundant and awkwardly phrased ('further information retrieving'), but it does add a usage hint without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has six parameters including section, readHeadings, and paragraphRange, the description only says 'Read the content' without explaining how output varies with these options. The schema describes parameters well, but the absence of an output schema and limited description leaves some ambiguity about return behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds no parameter-specific meaning, keeping this at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads content from a URL with a specific verb and resource. It is distinguishable from the sibling search tool, though it doesn't explicitly differentiate itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use this for further information retrieving to understand the content of each URL' provides a clear intended use case as a follow-up to retrieving URLs. It lacks explicit exclusions or alternative guidance, but the sibling name makes the contrast evident.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.1.0
    • First observedsearxng_web_search
    • First observedweb_url_read
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 2 tools

Disambiguation5/5

Each tool serves a distinct role: one performs web searches and the other reads specific URLs. There is no overlap in functionality, making them easy to distinguish.

Naming Consistency2/5

The naming pattern is inconsistent: one tool uses the 'searxng_' prefix while the other does not, and the action-object order differs (web_search vs url_read). This mixed convention could confuse an agent.

Tool Count3/5

With only 2 tools, the server feels minimal and is below the typical well-scoped range of 3-15. However, the two tools do cover a basic search-and-read workflow.

Completeness4/5

The pair covers the core search and content retrieval workflow, which is sufficient for basic information gathering. Minor gaps exist, such as no advanced search options, but these are not critical for a simple search server.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • SearXNG MCP Server

    The-AI-Workshops
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to perform privacy-respecting web searches through SearXNG, with support for multiple search engines, categories, and advanced filtering options.
    25
    -

  • SearXNG MCP Server

    ngc-shj
    A
    license
    A
    quality
    D
    maintenance
    Enables web search, image search, and news search through a self-hosted SearXNG instance. Provides privacy-focused meta-search capabilities aggregating results from multiple search engines.
    3
    1
    MIT

  • WebFetch.MCP

    manooll
    A
    license
    A
    quality
    B
    maintenance
    Enables local LLMs to search the web and fetch clean content from URLs without API keys, using SearxNG and Mozilla Readability.
    2
    36
    MIT