docs: add README with server usage and SearxNG Docker Compose setup

2026-04-20 11:46:43 +02:00 · 2026-04-20 11:46:43 +02:00 · 27e0805898
commit 27e0805898
parent 8885c1872f
1 changed files with 213 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,213 @@
+# 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, and pagination. |
+| `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, and in-memory caching. |
+| `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
+```
+
+All settings can also be provided as environment variables with the `SEARXNG_` prefix:
+
+```bash
+export SEARXNG_BASE_URL=http://localhost:8080
+```
+
+## 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`) |