searxng-mcp/README.md

# searxng-mcp

An [MCP](https://modelcontextprotocol.io/) server that exposes [SearxNG](https://searxng.github.io/searxng/) web search as tools for AI assistants and agents.

Built with [FastMCP](https://github.com/prefecthq/fastmcp).

## What it provides

| Name | Type | Description |
|------|------|-------------|
| `search` | Tool | Query the web via SearxNG. Supports categories, engines, language, time range, safe search, and pagination. |
| `fetch` | Tool | Fetch a URL and extract its main content (strips ads, navigation, boilerplate). Returns a preview with `total_chars` and `truncated` metadata. Supports `start`/`end` slicing, `max_chars`, multiple output formats, and in-memory caching. |
| `web://fetch{?url,...}` | Resource | Read an arbitrary character slice of a fetched page without going through the tool call. Useful for paging through large documents. |

## Requirements

- Python 3.14+
- [`uv`](https://docs.astral.sh/uv/) (recommended) or `pip`
- A running SearxNG instance (see below)

## Installation

```bash
git clone <repo-url>
cd searxng-mcp
uv sync
```

## Configuration

Copy `.env.example` to `.env` and set your SearxNG instance URL:

```bash
cp .env.example .env
```

`.env`:
```dotenv
SEARXNG_BASE_URL=http://localhost:8080
```

All settings can also be provided as environment variables with the `SEARXNG_` prefix:

```bash
export SEARXNG_BASE_URL=http://localhost:8080
```

## Starting the server

### stdio (default — for use with MCP clients like Claude Desktop)

```bash
uv run searxng-mcp
# or equivalently:
uv run python -m searxng_mcp
```

### HTTP transport (for use with remote MCP clients or mcp-forge)

```bash
uv run searxng-mcp --transport http --host 127.0.0.1 --port 8023
```

### SSE transport

```bash
uv run searxng-mcp --transport sse --host 127.0.0.1 --port 8023
```

All options:

```
usage: searxng-mcp [-h] [--transport {stdio,http,sse}] [--host HOST] [--port PORT]

  --transport   Transport protocol (default: stdio)
  --host        Host to bind for http/sse transports (default: 127.0.0.1)
  --port        Port to bind for http/sse transports (default: 8000)
```

## Connecting to an MCP client

### Claude Desktop

Add to `~/.config/claude/claude_desktop_config.json` (Linux) or the equivalent on your platform:

```json
{
  "mcpServers": {
    "searxng": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/searxng-mcp", "searxng-mcp"],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:8080"
      }
    }
  }
}
```

### OpenCode

Add to `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "searxng": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/path/to/searxng-mcp", "searxng-mcp"]
    }
  }
}
```

Or with HTTP transport (if the server is already running):

```json
{
  "mcp": {
    "searxng": {
      "type": "http",
      "url": "http://127.0.0.1:8023/mcp"
    }
  }
}
```

---

## Running SearxNG locally

If you don't have a SearxNG instance yet, the easiest way to get one running is with Docker Compose.

### Quick start with Docker Compose

```bash
# Create a working directory
mkdir -p ./searxng/core-config/
cd ./searxng/

# Fetch the official compose template
curl -fsSL \
  -O https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
  -O https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example

# Copy and (optionally) edit the environment file
cp .env.example .env

# Start SearxNG
docker compose up -d
```

SearxNG will be available at **http://localhost:8080**.

The `docker-compose.yml` starts two services:

```yaml
services:
  core:       # SearxNG itself, exposed on port 8080
  valkey:     # Redis-compatible cache (Valkey 9)
```

### Enabling the JSON API

By default SearxNG may have the JSON API disabled. Edit `core-config/settings.yml` to enable it:

```yaml
search:
  formats:
    - html
    - json
```

Then restart:

```bash
docker compose restart core
```

### Useful management commands

```bash
# View logs
docker compose logs -f core

# Stop everything
docker compose down

# Update to the latest SearxNG image
docker compose pull && docker compose up -d
```

For full documentation see [docs.searxng.org](https://docs.searxng.org/admin/installation-docker.html).

---

## Development

```bash
# Run tests (if any)
uv run pytest

# Run the server in development mode with HTTP transport
uv run searxng-mcp --transport http --port 8023
```

The source layout follows `src/searxng_mcp/`:

| File | Purpose |
|------|---------|
| `server.py` | FastMCP server — tools, resource, settings |
| `searxng.py` | Async SearxNG HTTP client |
| `__main__.py` | CLI entry point (`argparse`) |