# SearXNG MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides web search capabilities through [SearXNG](https://github.com/searxng/searxng) instances.

## Features

- 🔍 **Web Search** — Query any SearXNG instance for general web results
- 📁 **Category-Specific Search** — Search images, videos, news, music, science, etc.
- ⚙️ **Engine Selection** — Use specific search engines (Google, Bing, DuckDuckGo, etc.)
- 🕐 **Time Filtering** — Filter results by day, week, month, or year
- 📋 **Engine Discovery** — List all available SearXNG engines

## Installation

### From PyPI (when published)

```bash
pip install searxng-mcp-server
```

### From Source

```bash
git clone https://github.com/<username>/searxng-mcp-server.git
cd searxng-mcp-server
pip install -e ".[dev]"
```

## Configuration

Set the following environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `SEARXNG_URL` | SearXNG instance URL | `http://localhost:8888` (local Docker) |
| `SEARXNG_ENGINES` | Comma-separated engine list | (none — uses all) |
| `SEARXNG_LANG` | Search language code | `en-US` |

Example:

```bash
export SEARXNG_URL="http://localhost:8888"
export SEARXNG_ENGINES="google,bing,duckduckgo"
export SEARXNG_LANG="zh-TW"
```

## Usage with Hermes Agent

Add to `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  searxng:
    command: "uv"
    args: ["run", "--directory", "/path/to/searxng-mcp-server", "searxng-mcp"]
    env:
      SEARXNG_URL: "https://search.sapti.me"
```

## Usage with Claude Desktop / Cursor / VS Code

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "searxng": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/searxng-mcp-server", "searxng-mcp"],
      "env": {
        "SEARXNG_URL": "https://search.sapti.me"
      }
    }
  }
}
```

## Available Tools

### `search_web`

Search the web using a SearXNG instance.

**Parameters:**
- `query` (string, required): The search query
- `max_results` (int, optional): Maximum results to return (default: 10)
- `time_range` (string, optional): Filter by time — 'day', 'week', 'month', 'year'

### `search_specific`

Search using specific categories and/or engines.

**Parameters:**
- `query` (string, required): The search query
- `categories` (list of strings, optional): Categories to search (general, images, videos, news, music, files, it, science, social media)
- `engines` (list of strings, optional): Specific engines to use
- `max_results` (int, optional): Maximum results (default: 10)
- `time_range` (string, optional): Time filter

### `search_by_category`

Search a specific SearXNG category.

**Parameters:**
- `query` (string, required): The search query
- `category` (string, optional): Category to search (default: 'general')
- `max_results` (int, optional): Maximum results (default: 10)

### `list_engines`

List all available SearXNG search engines from searxng.org.

**Parameters:** None

## Development

```bash
# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Lint with ruff
ruff check src/ tests/
```

## Public SearXNG Instances

You can use any public or self-hosted SearXNG instance. Some public instances:

- `https://search.sapti.me`
- `https://searx.be`
- `https://search.ononoki.org`

> ⚠️ **Note:** Public instances may have rate limits or be unreliable. For production use, consider self-hosting your own SearXNG instance.

## License

MIT