searxng-mcp

MCP server that connects to a self-hosted SearXNG instance and exposes web search capabilities over MCP HTTP (JSON-RPC).

Overview

This service enables your AI chatbot to search the internet for real-time information via SearXNG, a privacy-respecting metasearch engine.

Use cases:

• Current weather, news, prices

• Recent documentation and updates

• Real-time information beyond the LLM's knowledge cutoff

Related MCP server: searxng-mcp

Environment

Required:

• SEARXNG_URL - Base URL of your SearXNG instance (e.g. http://searxng:8080).

• MCP_INTERNAL_TOKEN - Shared secret between homelab-chatbot-ui and searxng-mcp. Alias: SEARXNG_MCP_INTERNAL_TOKEN.

Optional:

• PORT - Server port. Defaults to 3003.

• SEARXNG_TIMEOUT_MS - Request timeout in milliseconds. Defaults to 10000.

Tools

web_search

Search the internet for current information.

Parameters:

Response:

{
  "status": "ok",
  "query": "weather hong kong",
  "resultCount": 5,
  "results": [
    {
      "title": "Hong Kong Weather Forecast",
      "url": "https://example.com/weather",
      "snippet": "Current conditions: 24°C, partly cloudy...",
      "source": "google",
      "date": "2024-01-15"
    }
  ],
  "formatted": "[1] Hong Kong Weather Forecast\n    URL: https://example.com/weather\n    Current conditions: 24°C..."
}

Endpoints

Authentication

All MCP endpoints require authentication via:

• Authorization header: Bearer <token> or plain <token>

• x-mcp-internal-token header: plain <token>

Development

# Install dependencies
npm install

# Build
npm run build

# Run (requires env vars)
SEARXNG_URL=http://localhost:8080 \
SEARXNG_MCP_INTERNAL_TOKEN=test-token \
npm start

# Run tests
npm test

Docker

# Build image
docker build -t searxng-mcp .

# Run container
docker run -p 3003:3003 \
  -e SEARXNG_URL=http://searxng:8080 \
  -e SEARXNG_MCP_INTERNAL_TOKEN=your-secret-token \
  searxng-mcp

Kubernetes

Deploy alongside your SearXNG instance:

# ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
  name: searxng-mcp-config
data:
  PORT: "3003"
  SEARXNG_URL: "http://searxng.app-searxng.svc.cluster.local:8080"
  SEARXNG_TIMEOUT_MS: "10000"

See deploy/k8s/base/ for full manifests.

Registering in Chatbot UI

1. Deploy this service

2. Go to Admin → Tools → Add Backend

3. Configure:

   • Type: mcp

   • Transport: http

   • URL: http://searxng-mcp.mcp-searxng.svc.cluster.local:3003/mcp

   • Auth Type: apiKey

   • API Key: Your SEARXNG_MCP_INTERNAL_TOKEN value

4. Click "Discover Tools" to auto-import the web_search tool

5. Enable the tool