# SearXNG MCP Server

A Model Context Protocol (MCP) server that provides privacy-focused web search capabilities through [SearXNG](https://github.com/searxng/searxng), using **Streamable HTTP transport**.

## Features

- **Privacy-Focused Search**: Leverages SearXNG for anonymous, tracker-free web searches
- **Streamable HTTP Transport**: Modern HTTP-based MCP protocol for remote access
- **Environment Variables**: All configuration via environment variables
- **HTTP Basic Auth**: Support for authentication-protected SearXNG instances
- **Advanced Search Parameters**: Support for categories, language filters, and time ranges
- **Async Architecture**: Built with async/await for non-blocking operations

## Installation

```bash
# Clone the repository
git clone <repo-url>
cd searxng-mcp

# Install dependencies
pip install -e .

# Or using uv
uv pip install -e .
```

## Configuration

All configuration is done via environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `SEARXNG_BASE_URL` | Base URL of your SearXNG instance | `http://127.0.0.1:8888` |
| `SEARXNG_USERNAME` | Username for HTTP Basic Auth (optional) | - |
| `SEARXNG_PASSWORD` | Password for HTTP Basic Auth (optional) | - |
| `SEARXNG_TIMEOUT` | Request timeout in seconds | `10` |
| `MAX_RESULTS_LIMIT` | Maximum results allowed per query | `50` |
| `HOST` | Server host address | `0.0.0.0` |
| `PORT` | Server port | `3000` |
| `BASE_URL` | Base URL path for the MCP server | `/searxng-mcp` |
| `LOG_LEVEL` | Logging verbosity | `INFO` |

### Using Environment File

Create a `searxng.env` file from the example:

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

Edit `searxng.env` with your settings:

```bash
# SearXNG Configuration
SEARXNG_BASE_URL=https://example.com/searxng
SEARXNG_USERNAME=your_username
SEARXNG_PASSWORD=your_password
SEARXNG_TIMEOUT=10
MAX_RESULTS_LIMIT=50

# Server Configuration
HOST=0.0.0.0
PORT=3000
BASE_URL=/searxng-mcp

# Logging
LOG_LEVEL=INFO
```

## Running

### Using Python (with env file)

```bash
# Load from searxng.env file and run
export $(grep -v '^#' searxng.env | xargs) && python -m searxng_mcp
```

### Using CLI

```bash
# With environment variables inline
SEARXNG_BASE_URL=https://example.com/searxng \
SEARXNG_USERNAME=your_username \
SEARXNG_PASSWORD=your_password \
searxng-mcp
```

### Using Docker

Build the image:

```bash
docker build -t searxng-mcp .
```

Run with environment file:

```bash
docker run -d \
  --name searxng-mcp \
  --env-file searxng.env \
  -p 127.0.0.1:3000:3000 \
  searxng-mcp
```

Run with inline environment variables:

```bash
docker run -d \
  --name searxng-mcp \
  -e SEARXNG_BASE_URL=https://example.com/searxng \
  -e SEARXNG_USERNAME=your_username \
  -e SEARXNG_PASSWORD=your_password \
  -e HOST=0.0.0.0 \
  -e PORT=3000 \
  -p 127.0.0.1:3000:3000 \
  searxng-mcp
```

## SearXNG Instance

You need a running SearXNG instance. Options:

- **Local**: `docker run -d --name searxng -p 8888:8080 searxng/searxng:latest`
- **Remote**: Use any public or private SearXNG instance

If your SearXNG instance is protected with HTTP Basic Auth, set `SEARXNG_USERNAME` and `SEARXNG_PASSWORD`.

## MCP Client Configuration

Configure your MCP client to connect to this server:

```json
{
  "mcpServers": {
    "searxng": {
      "type": "streamable-http",
      "url": "http://localhost:3000"
    }
  }
}
```

If using a reverse proxy:

```json
{
  "mcpServers": {
    "searxng": {
      "type": "streamable-http",
      "url": "http://your-server/searxng-mcp"
    }
  }
}
```

## Usage

Once connected, use the `web_search` tool:

### Basic Search
```
Search for "Python async programming tutorials"
```

### Search with Maximum Results
```
Search for "machine learning news" with max_results=20
```

### Category-Specific Search

Available categories:
- `general` - General web search
- `news` - News articles
- `images` - Image search
- `videos` - Video content
- `files` - File downloads
- `science` - Scientific papers and resources
- `it` - IT and tech resources

### Language-Specific Search
Use ISO 639-1 language codes: `en`, `de`, `fr`, `es`, `zh`, `ja`, etc.

### Time-Range Filtered Search
Available time ranges: `day`, `week`, `month`, `year`

## Using with Reverse Proxy

For production deployment with a custom base URL, use a reverse proxy:

### Nginx Example
```nginx
location /searxng-mcp/ {
    proxy_pass http://127.0.0.1:3000/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}
```

## License

MIT License