Privacy-Preserving Web Search Extension for AI Agents (MCP Server)

This repository furnishes a Model Context Protocol (MCP) server implementation, specifically utilizing Server-Sent Events (SSE) for transport, which interfaces directly with a running SearXNG instance. Its primary function is to equip AI entities with robust, non-logging web search functionality.

---

Architectural Overview

This project serves as a template demonstrating how to construct an MCP server backend leveraging SearXNG for external data acquisition. It strictly adheres to the integration guidelines established by Anthropic for MCP server development, ensuring compatibility across all conforming client environments.

---

Prerequisites for Local Setup

To successfully deploy and operate this utility, the following runtime components are necessary:

• Python interpreter version 3.9 or higher.
• Reachability to an operational SearXNG instance (local container or remote service).
• Docker (highly recommended for simplified deployment).
• The uv package manager (optional, for accelerated dependency resolution).
• The Smithery tool (optional, for standardized MCP orchestration).

SearXNG Backend Requirement

A functional SearXNG server endpoint is mandatory. The default configuration expects it to be reachable at http://172.17.0.1:32768 unless overridden in the environment variables.

Example Docker startup for the required backend:

docker run -d --name=searxng-privacy -p 32768:8080 -v "/data/searxng_config:/etc/searxng" \
  -e "BASE_URL=http://0.0.0.0:32768/" \
  -e "INSTANCE_NAME=private-proxy" \
  --restart always searxng/searxng

---

Deployment Procedures

Method 1: Python Environment Management with uv

1. Install uv if absent: bash pip install uv
2. Clone the source repository: bash git clone https://github.com/The-AI-Workshops/searxng-mcp-server.git cd searxng-mcp-server/dev/searXNG-mcp
3. Install dependencies using uv: bash uv pip install -r requirements.txt
4. Initialize and populate the environment configuration file: bash cp .env.example .env # Modify settings in .env

---

Method 2: Containerized Deployment (Preferred)

1. Construct the Docker artifact: bash docker build -t mcp-extensions/searxng-proxy .
2. Ensure your .env configuration file is prepared.
3. Execute the service container:

bash docker run -d --env-file ./.env -p 32769:32769 mcp-extensions/searxng-proxy

---

Method 3: Integration via Smithery Orchestrator

If utilizing Smithery for toolchain management:

1. Install Smithery (e.g., via pipx install smithery).
2. Register the extension package: bash smithery install @The-AI-Workshops/searxng-mcp-server
3. Navigate to the newly provisioned tool directory (e.g., ~/.smithery/tools/The-AI-Workshops/searxng-mcp-server).
4. Copy and tailor the example configuration file (cp .env.example .env).

---

Runtime Configuration Variables

Adjust settings within the .env file to customize server behavior:

Variable	Purpose	Sample Value
SEARXNG_BASE_URL	Endpoint URI for the SearXNG service.	http://172.17.0.1:32768
HOST	Network interface binding address for SSE.	0.0.0.0
PORT	Network port exposed for SSE communication.	32769
TRANSPORT	Communication modality (sse or stdio).	sse

---

Initiating the Server Process

Execution with uv (Local Python)

SSE Mode (Networked Service): Configure TRANSPORT=sse in .env, then:

uv run dev/searXNG-mcp/server.py

Stdio Mode (Inter-process Communication): No explicit server startup needed; the consuming client manages execution.

---

Execution with Docker

SSE Mode:

docker build -t mcp-extensions/searxng-proxy .
docker run --rm -it -p 32769:32769 --env-file dev/searXNG-mcp/.env -v $(pwd)/dev/searXNG-mcp:/app mcp-extensions/searxng-proxy

Access point: http://localhost:32769/sse.

Stdio Mode: The client launches the container directly.

---

Execution via Smithery

SSE Mode: Set TRANSPORT=sse in the tool's .env. Invoke via the managed environment:

# In the Smithery tool directory:
~/.smithery/venvs/The-AI-Workshops_searxng-mcp-server/bin/python server.py
# OR
smithery run @The-AI-Workshops/searxng-mcp-server

Stdio Mode: The client invokes the server script directly within the isolated Smithery environment (see Integration section for client configuration examples).

---

Client Integration Schemas

SSE Endpoint Configuration

For standard MCP clients connecting via network stream:

{
  "mcpServers": {
    "privacy_search_engine": {
      "transport": "sse",
      "url": "http://localhost:32769/sse"
    }
  }
}

Windsurf Modification: Replace url with serverUrl.

n8n/Docker Host Context: Replace localhost with host.docker.internal.

Stdio Command-Line Configuration

To enable client-side process management (e.g., for local execution or containerized execution managed by the client):

Python Stdio Example:

{
  "mcpServers": {
    "privacy_search_engine": {
      "command": "python",
      "args": ["dev/searXNG-mcp/server.py"],
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://127.0.0.1:32768"
      }
    }
  }
}

Docker Stdio Example (Client invokes Docker):

{
  "mcpServers": {
    "privacy_search_engine": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "TRANSPORT", "-e", "SEARXNG_BASE_URL", "mcp-extensions/searxng-proxy"],
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://host.docker.internal:32768" 
      }
    }
  }
}

Smithery Stdio Example (Leveraging smithery exec):

{
  "mcpServers": {
    "privacy_search_engine": {
      "command": "smithery",
      "args": ["exec", "@The-AI-Workshops/searxng-mcp-server", "--", "python", "server.py"],
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://127.0.0.1:32768"
      }
    }
  }
}

---

Customizing the Toolset

This structure is designed for extensibility. To incorporate proprietary tools or resources into the search agent interface:

• Define new functionalities using the @mcp.tool() decorator.
• Initialize custom services (e.g., persistent storage connections) within the @mcp.lifespan() context manager.
• Register supplementary data sources via @mcp.resource() and @mcp.prompt().

---

SearXNG Query Parameters Reference

The exposed search operation accepts query modifiers, mirroring SearXNG's capabilities:

Parameter	Role	Mandatory	Available Values/Notes
q	The core investigative query text.	YES	String content.
categories	Filters results by specified types.	NO	Comma-delimited list.
engines	Selects specific search providers.	NO	Comma-delimited list.
language	Desired language code for results.	NO	Standard language codes (e.g., 'en').
page	Index of the result set page.	NO	Integer (default: 1).
time_range	Temporal scope filter.	NO	One of: [day, month, year].
format	Output serialization type.	NO	Default: json; options include csv, rss.
safesearch	Content restriction level.	NO	Integers 0, 1, or 2.
... [Other optional engine-specific flags] ...		NO	Refer to official SearXNG documentation for exhaustive options.

---

Governing Agreement

This project is released under the MIT License.

BACKGROUND ON CLOUD COMPUTING (ISO Context): Cloud computing represents an architectural model allowing ubiquitous, convenient, on-demand access to a shared reservoir of configurable computing assets (physical or virtual), facilitating self-service provisioning and operational oversight on a consumption basis, as defined by ISO standards. This concept is broadly termed "the cloud."

Key Attributes (NIST 2011):

1. Independent Provisioning: Consumers acquire computational capacity (e.g., server cycles, storage space) autonomously, without requiring direct engagement with the service provider's personnel.
2. Ubiquitous Network Accessibility: Services are deliverable across networks and accessible via standardized interfaces compatible with diverse client hardware (mobile, desktop).
3. Shared Resource Abstraction: Provider resources are pooled, employing multi-tenancy, with dynamic allocation to satisfy concurrent consumer demands.
4. Dynamic Scalability: Capacity can be instantly scaled both up and down, often automatically, to perfectly mirror fluctuating load requirements, giving the impression of near-infinite supply.
5. Consumption Metering: Resource utilization (e.g., processing time, data transfer) is automatically tracked, controlled, and reported, ensuring transparency for both service provider and consumer.

Historical Context:

The conceptual foundation traces back to the 1960s with the advancement of time-sharing systems facilitating remote job execution. Early mainframe operations centered on job submission managed by specialized operators. The actual 'cloud' graphical metaphor for abstracted, virtualized services emerged around 1994, notably at General Magic. Its widespread adoption into the computing lexicon gained traction in 1996.