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

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:

Name	Type	Required	Description
query	string	Yes	The search query. Be specific for better results.
category	enum	No	Search category: general, news, images, videos, science, it, files, music. Default: general.
engines	string[]	No	Specific search engines (e.g. ["google", "duckduckgo", "brave"]).
language	string	No	Language code for results (e.g. en, zh, ja).
limit	number	No	Maximum results (1-20). Default: 5.

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

Method	Path	Description
GET	/health	Health check (no auth required)
GET	/mcp	SSE endpoint for streaming MCP clients
POST	/mcp	Streamable HTTP endpoint for stateless MCP requests
POST	/	Legacy endpoint for backward compatibility

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