# mcp-searxng

A fork of `mcp-searxng`: an [MCP server](https://modelcontextprotocol.io/introduction) for querying a SearXNG instance from an MCP client.

This fork keeps the package name `mcp-searxng`, adds structured search-oriented tools, and disables arbitrary direct URL reads by default.

Repository: `https://git.carpocratian.org/sibyl/mcp-searxng.git`

## What This Fork Does

- Exposes SearXNG-backed search tools over MCP
- Returns normalized structured search results by default
- Supports dedicated news, image, video, and research evidence tools
- Keeps `web_url_read` available only behind `ENABLE_WEB_URL_READ=true`
- Supports both STDIO and HTTP transport

## Security Posture

The direct `web_url_read` tool is disabled by default in this fork.

That means:

- `searxng_research` still performs controlled internal reads of selected search results
- internal fetch-and-convert logic still exists for top search results
- arbitrary user-supplied URL reads are not exposed unless you opt in

To enable direct URL reads in a trusted deployment:

```bash
ENABLE_WEB_URL_READ=true
```

If you expose the HTTP transport on a network, also use the hardened HTTP settings described in [CONFIGURATION.md](/Users/edith/mcp-searxng/CONFIGURATION.md:1).

## Build

```bash
git clone https://git.carpocratian.org/sibyl/mcp-searxng.git
cd mcp-searxng
npm install
npm run build
```

## Quick Start

![](quick-start.png)

Example MCP client configuration using the local build:

```json
{
  "mcpServers": {
    "searxng": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-searxng/dist/index.js"],
      "env": {
        "SEARXNG_URL": "https://search.example.com"
      }
    }
  }
}
```

## Tools

### `searxng_web_search`

General SearXNG search with structured normalized output by default.

Key inputs:

- `query`
- `pageno`
- `categories`
- `engines`
- `time_range`
- `language`
- `response_mode`

### `searxng_news_headlines`

![](searxng_news_headlines.png)

News-focused wrapper around SearXNG with `news` category and same-day recency defaults.

### `searxng_image_search`

Image-focused wrapper around SearXNG.

### `searxng_video_search`

![](searxng_video_search.png)

Video-focused wrapper around SearXNG.

### `searxng_research`

Searches first, reads selected result pages, chunks the Markdown, and returns ranked source evidence.

Key inputs:

- `query`
- `max_results`
- `max_chunks`
- `max_chunks_per_source`
- `max_content_length`
- `chunk_target_chars`
- `chunk_overlap_chars`

### `web_url_read`

Disabled by default.

Enable it only for trusted deployments:

```bash
ENABLE_WEB_URL_READ=true
```

## Transport

By default the server uses STDIO.

To enable HTTP transport:

```bash
MCP_HTTP_PORT=3000
```

HTTP mode exposes:

- `POST /mcp`
- `GET /mcp`
- `DELETE /mcp`
- `GET /health`

## Configuration

The most important variables are:

- `SEARXNG_URL`
- `ENABLE_WEB_URL_READ`
- `MCP_HTTP_PORT`
- `MCP_HTTP_HARDEN`
- `MCP_HTTP_AUTH_TOKEN`
- `MCP_HTTP_ALLOWED_ORIGINS`
- `MCP_SERVER_NAME`

Full reference: [CONFIGURATION.md](/Users/edith/mcp-searxng/CONFIGURATION.md:1)

## Development

```bash
npm test
npm run build
```

## Notes

- This fork currently keeps the original package name.
- The MCP package identifier in `package.json` still reflects the upstream namespace.