# 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:**

```json
{
  "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

```bash
# 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

```bash
# 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:

```yaml
# 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