[![PyPI Version](https://img.shields.io/pypi/v/searxng.svg)](https://pypi.org/project/searxng)
[![License](https://img.shields.io/pypi/l/searxng.svg)](https://pypi.org/project/searxng)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/searxng?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=BLUE&left_text=downloads)](https://pypi.org/project/searxng)

# SearXNG MCP Server

<!-- mcp-name: io.github.danchev/searxng -->

A Model Context Protocol (MCP) server that equips AI agents with privacy-friendly web search capabilities using the [SearXNG](https://github.com/searxng/searxng) metasearch engine.

## Features

This server provides the following main features:

- Web search via multiple search engines
- Supports various search categories (general, images, news, etc.)
- Customizable search engine selection
- Language filtering
- Time range filtering
- Control over the number of search results

## Available Tools

- `web_search` - Perform web search using SearXNG
  - Required parameters:
    - `query` (string): The search query
  - Optional parameters:
    - `categories` (array): Search categories, e.g. ['general', 'images', 'news']
    - `engines` (array): Search engines, e.g. ['google', 'bing', 'duckduckgo']
    - `language` (string): Language code for search, default is "en"
    - `max_results` (integer): Maximum number of results, default is 10 (1-100)
    - `time_range` (string): Time range filter ('day', 'week', 'month', 'year')

If a search cannot be completed (the instance is unreachable, rate-limits the
request, or returns a malformed response), the tool returns an error result
describing the failure rather than an empty result list.

## Search Limits

Each server process admits up to eight concurrent searches. Further calls return
an error immediately and can be retried later. `--timeout` bounds the complete
network operation, including streaming the response; cancellation closes the
active request. Responses are limited to 2 MiB before JSON parsing.

The configured instance must serve `/search` directly: redirects are rejected.
The client requests `Accept-Encoding: identity` and rejects compressed responses
to prevent unbounded decompression. Result fields are also truncated to their
existing limits. Missing or non-list `results` and upstream error objects are
reported as failures, while a valid empty list remains a successful search.

Application logs omit search queries and upstream exception text. The CLI keeps
HTTP dependency logging at WARNING even when `--log-level=DEBUG` is selected.

## Privacy Policy

This software does not operate a hosted search service and does not send search
queries to its maintainer. It runs on the user's device or infrastructure and
sends each query, selected engines, categories, language, time range, and safe
search setting directly to the configured SearXNG instance. Search results are
returned to the connected MCP client.

The software does not persist queries or results, use analytics or advertising
trackers, create user profiles, or share data with the maintainer. Operational
logs record result counts and errors but omit query text and upstream exception
details. In-memory request and result data is discarded after the request.

The selected SearXNG instance and the search engines it contacts are independent
third parties. Their collection, use, sharing, and retention practices are
governed by their own privacy policies. Before sending sensitive queries, users
should review the selected instance's privacy notice or operate an instance they
trust. The default CLI instance is `https://searx.party`; its policy is at
<https://searx.party/info/en/privacy>.

Privacy questions and requests can be filed at
<https://github.com/danchev/searXNG/issues>.

## Command Line Options

| Option | Default | Description |
| --- | --- | --- |
| `--instance-url` | `https://searx.party` | SearXNG instance base URL. Must be absolute and cannot contain credentials, a query string, or a fragment. |
| `--timeout` | `30` | Total search network timeout, in seconds. |
| `--log-level` | `WARNING` | Logging verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. Logs are written to stderr. |
| `--transport` | `stdio` | Transport to serve on: `stdio` or `http`. |
| `--host` | `127.0.0.1` | Host to bind when `--transport=http`. |
| `--port` | `8000` | Port to bind when `--transport=http`. |
| `--header` | `None` | Custom HTTP headers to send with search requests (e.g., `X-Forwarded-For: 1.2.3.4`). Can be specified multiple times. |

## Docker / Kubernetes

You can run the server easily using the official container image published to the GitHub Container Registry:

```bash
docker run -p 8000:8000 ghcr.io/danchev/searxng:latest \
    --transport http \
    --host 0.0.0.0 \
    --instance-url=https://searx.party \
    --header "Authorization: Bearer my-secret-token"
```

## Transports

By default the server speaks **stdio**, which is what local MCP clients
(Claude Desktop, IDE integrations, `uvx`) launch it with.

For remote access, `--transport http` serves the **Streamable HTTP**
transport at `/mcp`:

```bash
searxng --transport http --host 127.0.0.1 --port 8000
# endpoint: http://127.0.0.1:8000/mcp
```

> The legacy SSE transport is intentionally not implemented. It was
> superseded by Streamable HTTP in the 2025-03-26 MCP protocol revision
> and should not be used for new deployments.

**Security:** the server performs no authentication, so it binds to
`127.0.0.1` by default. Only pass `--host 0.0.0.0` on a trusted network,
or put an authenticating reverse proxy in front of it.

Binding to a non-loopback host also disables the MCP SDK's DNS-rebinding
protection, which it can only enable automatically for `127.0.0.1`,
`localhost`, and `::1`. On a loopback bind a forged `Host` header is
rejected with `421 Misdirected Request`; on a public bind any `Host` is
accepted. The server logs a warning at startup when this applies.

## Usage Example

### Configure as an MCP Service

To set up SearXNG as an MCP server, add one of the following to your MCP configuration file:

**UVX setup:**
```json
"mcpServers": {
  "searxng": {
    "command": "uvx",
    "args": ["searxng", "--instance-url=https://searx.party"]
  }
}
```

**Docker setup (Local stdio):**
```json
"mcpServers": {
  "searxng": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "ghcr.io/danchev/searxng:latest",
      "--instance-url=https://searx.party"
    ]
  }
}
```

This launches the server over stdio, which is the right choice for a
local client.

**Remote setup (Streamable HTTP):**

Start the server as a long-running process:

```bash
searxng --transport http --host 0.0.0.0 --port 8000 \
        --instance-url=https://searx.party
```

Then point the client at its `/mcp` endpoint:

```json
"mcpServers": {
  "searxng": {
    "url": "http://your-host:8000/mcp"
  }
}
```

Note the `--host 0.0.0.0` needed to accept connections from other
machines, and the security caveat above: the server is unauthenticated,
so restrict it to a trusted network or front it with an authenticating
reverse proxy.

### Example Invocation

1.
```json
{
  "name": "web_search",
  "arguments": {
    "query": "climate change research",
    "categories": ["general"],
    "engines": ["google"],
    "language": "en",
    "max_results": 15,
    "time_range": "month"
  }
}
```

## Debugging

You can use the MCP inspector to debug the server:

```bash
npx @modelcontextprotocol/inspector uvx searxng
```

## License

AGPLv3+ License - see [LICENSE](LICENSE) for details.