Metadata-Version: 2.4
Name: searXNG
Version: 0.1.2
Summary: MCP server providing SearXNG-based web search functionality
Author: D. Danchev
Author-email: D. Danchev <12420863+danchev@users.noreply.github.com>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Dist: mcp[cli]>=2.0.0
Requires-Dist: httpx2>=2.9.1,<3
Requires-Dist: uvicorn>=0.34.0
Requires-Python: >=3.11
Project-URL: Source, https://github.com/danchev/searXNG
Project-URL: Documentation, https://danchev.github.io/searXNG/
Project-URL: Issues, https://github.com/danchev/searXNG/issues
Description-Content-Type: text/markdown

[![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-name: io.github.danchev/searxng -->

A network search server based on MCP technology, providing privacy-friendly web search functionality using the [SearXNG](https://github.com/searxng/searxng) search 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.

## Command Line Options

| Option | Default | Description |
| --- | --- | --- |
| `--instance-url` | `https://searx.party` | SearXNG instance to query. Must be an absolute `http(s)` URL. |
| `--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`. |

## 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"]
  }
}
```

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.
