# searxng-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server that gives any MCP-capable
agent (Claude Desktop, AiderDesk, OpenCode, Goose, …) web search and page reading through a
**self-hosted [SearXNG](https://github.com/searxng/searxng)** instance — no API key, no
per-query metering, and your queries never leave your network before SearXNG fans them out.

Built as a drop-in replacement after two metered search-API keys ran out of quota on the
same day.

## Tools

| Tool | What it does |
|---|---|
| `searxng_search` | General search. Categories, time range, language, safesearch, engines, paging, `max_results`. |
| `searxng_search_news` | News-category shortcut with a recency window (default: past week). |
| `searxng_extract` | Fetch up to 10 URLs and return readable text — scripts/styles/nav stripped, `<article>`/`<main>` preferred, entities decoded, size/timeout guarded. |
| `searxng_search_and_extract` | Search, then fetch the full text of the top *n* results in one call (the "advanced search depth" pattern). |

Behaviour worth knowing:

- **Silent-zero detection.** SearXNG returns HTTP 200 with an empty result list when its
  upstream engines are CAPTCHA-blocked or rate-limited. The server treats that as a miss and
  retries through fallback engine sets (`bing,yandex` → `google,duckduckgo,brave,startpage` →
  `mojeek,wikipedia,wiby`) before returning, and reports which set answered.
- Engine names are category-specific in SearXNG (`bing` vs `bing news`); the server picks
  the right defaults per category.
- Extraction refuses non-text content types and pages over 3 MB, and truncates at a
  configurable character limit with an explicit marker.

## Setup

You need a SearXNG instance with the JSON format enabled (`search.formats: [html, json]` in
`settings.yml`). The quickest way is the official Docker image on port 8080.

```bash
npm install
SEARXNG_URL=http://your-searxng:8080 node server.mjs
```

Register it with your MCP client (stdio transport):

```json
{
  "mcpServers": {
    "searxng": {
      "command": "node",
      "args": ["/path/to/searxng-mcp/server.mjs"],
      "env": { "SEARXNG_URL": "http://your-searxng:8080" }
    }
  }
}
```

### Environment

| Variable | Default | Purpose |
|---|---|---|
| `SEARXNG_URL` | `http://localhost:8080` | Base URL of your instance |
| `SEARXNG_TIMEOUT_MS` | `30000` | Per-request timeout |
| `SEARXNG_ENGINES` | `bing,yandex` | Primary engines for general search |
| `SEARXNG_NEWS_ENGINES` | `bing news,yandex` | Primary engines for news |

## Smoke test

```bash
npm test          # spawns the server over stdio and exercises all four tools against your instance
```

## License

MIT — see [LICENSE](LICENSE).