searxng-mcp

An MCP server that exposes SearxNG web search as tools for AI assistants and agents.

Built with FastMCP.

What it provides

Name	Type	Description
search	Tool	Query the web via SearxNG. Supports categories, engines, language, time range, safe search, pagination, and per-call timeout overrides.
fetch	Tool	Fetch a URL and extract its main content (strips ads, navigation, boilerplate). Returns a preview with total_chars and truncated metadata. Supports start/end slicing, max_chars, multiple output formats, in-memory caching, and per-call timeout overrides.
web://fetch{?url,...}	Resource	Read an arbitrary character slice of a fetched page without going through the tool call. Useful for paging through large documents.

Requirements

• Python 3.14+
• uv (recommended) or pip
• A running SearxNG instance (see below)

Installation

git clone <repo-url>
cd searxng-mcp
uv sync

Configuration

Copy .env.example to .env and set your SearxNG instance URL:

cp .env.example .env

.env:

SEARXNG_BASE_URL=http://localhost:8080
SEARXNG_REQUEST_TIMEOUT_SECONDS=30

All settings can also be provided as environment variables with the SEARXNG_ prefix:

export SEARXNG_BASE_URL=http://localhost:8080
export SEARXNG_REQUEST_TIMEOUT_SECONDS=30

Timeout behavior:

• SEARXNG_REQUEST_TIMEOUT_SECONDS sets the default timeout for outgoing HTTP calls.
• search, fetch, fetch_raw, and web://fetch accept optional timeout_seconds to override the default for a single call.

Starting the server

stdio (default — for use with MCP clients like Claude Desktop)

uv run searxng-mcp
# or equivalently:
uv run python -m searxng_mcp

HTTP transport (for use with remote MCP clients or mcp-forge)

uv run searxng-mcp --transport http --host 127.0.0.1 --port 8023

SSE transport

uv run searxng-mcp --transport sse --host 127.0.0.1 --port 8023

All options:

usage: searxng-mcp [-h] [--transport {stdio,http,sse}] [--host HOST] [--port PORT]

  --transport   Transport protocol (default: stdio)
  --host        Host to bind for http/sse transports (default: 127.0.0.1)
  --port        Port to bind for http/sse transports (default: 8000)

Connecting to an MCP client

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json (Linux) or the equivalent on your platform:

{
  "mcpServers": {
    "searxng": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/searxng-mcp", "searxng-mcp"],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:8080"
      }
    }
  }
}

OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "searxng": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/path/to/searxng-mcp", "searxng-mcp"]
    }
  }
}

Or with HTTP transport (if the server is already running):

{
  "mcp": {
    "searxng": {
      "type": "http",
      "url": "http://127.0.0.1:8023/mcp"
    }
  }
}

---

Running SearxNG locally

If you don't have a SearxNG instance yet, the easiest way to get one running is with Docker Compose.

Quick start with Docker Compose

# Create a working directory
mkdir -p ./searxng/core-config/
cd ./searxng/

# Fetch the official compose template
curl -fsSL \
  -O https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
  -O https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example

# Copy and (optionally) edit the environment file
cp .env.example .env

# Start SearxNG
docker compose up -d

SearxNG will be available at http://localhost:8080.

The docker-compose.yml starts two services:

services:
  core:       # SearxNG itself, exposed on port 8080
  valkey:     # Redis-compatible cache (Valkey 9)

Enabling the JSON API

By default SearxNG may have the JSON API disabled. Edit core-config/settings.yml to enable it:

search:
  formats:
    - html
    - json

Then restart:

docker compose restart core

Useful management commands

# View logs
docker compose logs -f core

# Stop everything
docker compose down

# Update to the latest SearxNG image
docker compose pull && docker compose up -d

For full documentation see docs.searxng.org.

---

Development

# Run tests (if any)
uv run pytest

# Run the server in development mode with HTTP transport
uv run searxng-mcp --transport http --port 8023

The source layout follows src/searxng_mcp/:

File	Purpose
server.py	FastMCP server — tools, resource, settings
searxng.py	Async SearxNG HTTP client
__main__.py	CLI entry point (argparse)