219 lines
5 KiB
Markdown
219 lines
5 KiB
Markdown
# 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, pagination, and per-call timeout overrides. |
|
|
| `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, in-memory caching, and per-call timeout overrides. |
|
|
| `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
|
|
SEARXNG_REQUEST_TIMEOUT_SECONDS=30
|
|
```
|
|
|
|
All settings can also be provided as environment variables with the `SEARXNG_` prefix:
|
|
|
|
```bash
|
|
export SEARXNG_BASE_URL=http://localhost:8080
|
|
export SEARXNG_REQUEST_TIMEOUT_SECONDS=30
|
|
```
|
|
|
|
Timeout behavior:
|
|
- `SEARXNG_REQUEST_TIMEOUT_SECONDS` sets the default timeout for outgoing HTTP calls.
|
|
- `search`, `fetch`, `fetch_raw`, and `web://fetch` accept optional `timeout_seconds` to override the default for a single call.
|
|
|
|
## 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`) |
|