# searxng-mcp

MCP server for web search via a self-hosted [SearXNG](https://docs.searxng.org/) instance.

Provides a single `search_web` tool that queries your SearXNG instance and returns structured results (title, URL, snippet).

## Setup

### 1. Set environment variable

```bash
export SEARXNG_BASE_URL="http://searxng:8080"
```

Optional:

```bash
export SEARXNG_LANGUAGE="en-US"
export SEARXNG_CATEGORIES="general"
export SEARXNG_ENGINES="google,bing"
export SEARXNG_TIME_RANGE="month"
export SEARXNG_SAFESEARCH="1"
export SEARXNG_USER_AGENT="my-app/1.0"
export SEARXNG_HEADERS_JSON='{"Authorization":"Bearer ..."}'
export SEARXNG_TIMEOUT_SECONDS="30"
```

### 2. Run

No install needed — run directly from GitHub with `uvx`:

```bash
uvx --from "git+https://github.com/fighter3005/search-mcp" searxng-mcp
```

Or from a local clone:

```bash
uvx --from /path/to/search-mcp searxng-mcp
```

## Client configuration

### Claude Code

```bash
claude mcp add --transport stdio searxng-search \
  -e SEARXNG_BASE_URL="http://searxng:8080" \
  -- uvx --from "git+https://github.com/fighter3005/search-mcp" searxng-mcp
```

### Codex

```bash
codex mcp add searxng-search \
  --env SEARXNG_BASE_URL="http://searxng:8080" \
  -- uvx --from "git+https://github.com/fighter3005/search-mcp" searxng-mcp
```

### Cursor / VS Code

Create `.cursor/mcp.json` or `.vscode/mcp.json`:

**With uvx from GitHub:**

```json
{
  "mcpServers": {
    "searxng-search": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/fighter3005/search-mcp", "searxng-mcp"],
      "env": {
        "SEARXNG_BASE_URL": "http://searxng:8080"
      }
    }
  }
}
```

**After install:**

```json
{
  "mcpServers": {
    "searxng-search": {
      "command": "searxng-mcp",
      "env": {
        "SEARXNG_BASE_URL": "http://searxng:8080"
      }
    }
  }
}
```

### Claude Desktop

Edit `claude_desktop_config.json`:

**With uvx from GitHub (no install needed):**

```json
{
  "mcpServers": {
    "searxng-search": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/fighter3005/search-mcp", "searxng-mcp"],
      "env": {
        "SEARXNG_BASE_URL": "http://searxng:8080"
      }
    }
  }
}
```

**After install (`pip install -e .`):**

```json
{
  "mcpServers": {
    "searxng-search": {
      "command": "searxng-mcp",
      "env": {
        "SEARXNG_BASE_URL": "http://searxng:8080"
      }
    }
  }
}
```

### LiteLLM / Anthropic

Add to your `config.yaml`:

```yaml
mcp_servers:
  searxng-search:
    command: uvx
    args:
      - "--from"
      - "git+https://github.com/fighter3005/search-mcp"
      - "searxng-mcp"
    env:
      SEARXNG_BASE_URL: "http://searxng:8080"
```

Or as a JSON `litellm_config`:

```json
{
  "mcp_servers": {
    "searxng-search": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/fighter3005/search-mcp", "searxng-mcp"],
      "env": {
        "SEARXNG_BASE_URL": "http://searxng:8080"
      }
    }
  }
}
```

## Tool

| Tool | Parameters | Description |
|------|-----------|-------------|
| `search_web` | `query` (str), `num_results` (int, default 5) | Search the web via SearXNG |

Returns `{"results": [{"title": str, "url": str, "snippet": str}, ...]}`.

## Requirements

- Python 3.11+
- A running SearXNG instance with JSON format enabled