SearXNG MCP Server

1# SearXNG MCP Server
2 
3An [MCP server](https://modelcontextprotocol.io/introduction) implementation that integrates the [SearXNG](https://docs.searxng.org) API, providing web search capabilities.
4 
5[![https://nodei.co/npm/mcp-searxng.png?downloads=true&downloadRank=true&stars=true](https://nodei.co/npm/mcp-searxng.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/mcp-searxng)
6 
7[![https://badgen.net/docker/pulls/isokoliuk/mcp-searxng](https://badgen.net/docker/pulls/isokoliuk/mcp-searxng)](https://hub.docker.com/r/isokoliuk/mcp-searxng)
8 
9<a href="https://glama.ai/mcp/servers/0j7jjyt7m9"><img width="380" height="200" src="https://glama.ai/mcp/servers/0j7jjyt7m9/badge" alt="SearXNG Server MCP server" /></a>
10 
11## Features
12 
13- **Web Search**: General queries, news, articles, with pagination.
14- **URL Content Reading**: Advanced content extraction with pagination, section filtering, and heading extraction.
15- **Intelligent Caching**: URL content is cached with TTL (Time-To-Live) to improve performance and reduce redundant requests.
16- **Pagination**: Control which page of results to retrieve.
17- **Time Filtering**: Filter results by time range (day, month, year).
18- **Language Selection**: Filter results by preferred language.
19- **Safe Search**: Control content filtering level for search results.
20 
21## Tools
22 
23- **searxng_web_search**
24  - Execute web searches with pagination
25  - Inputs:
26    - `query` (string): The search query. This string is passed to external search services.
27    - `pageno` (number, optional): Search page number, starts at 1 (default 1)
28    - `time_range` (string, optional): Filter results by time range - one of: "day", "month", "year" (default: none)
29    - `language` (string, optional): Language code for results (e.g., "en", "fr", "de") or "all" (default: "all")
30    - `safesearch` (number, optional): Safe search filter level (0: None, 1: Moderate, 2: Strict) (default: instance setting)
31 
32- **web_url_read**
33  - Read and convert the content from a URL to markdown with advanced content extraction options
34  - Inputs:
35    - `url` (string): The URL to fetch and process
36    - `startChar` (number, optional): Starting character position for content extraction (default: 0)
37    - `maxLength` (number, optional): Maximum number of characters to return
38    - `section` (string, optional): Extract content under a specific heading (searches for heading text)
39    - `paragraphRange` (string, optional): Return specific paragraph ranges (e.g., '1-5', '3', '10-')
40    - `readHeadings` (boolean, optional): Return only a list of headings instead of full content
41 
42## Configuration
43 
44### Environment Variables
45 
46#### Required
47- **`SEARXNG_URL`**: SearXNG instance URL (default: `http://localhost:8080`)
48  - Format: `<protocol>://<hostname>[:<port>]`
49  - Example: `https://search.example.com`
50 
51#### Optional
52- **`AUTH_USERNAME`** / **`AUTH_PASSWORD`**: HTTP Basic Auth credentials for password-protected instances
53- **`USER_AGENT`**: Custom User-Agent header (e.g., `MyBot/1.0`)
54- **`HTTP_PROXY`** / **`HTTPS_PROXY`**: Proxy URLs for routing traffic
55  - Format: `http://[username:password@]proxy.host:port`
56- **`NO_PROXY`**: Comma-separated bypass list (e.g., `localhost,.internal,example.com`)
57 
58## Installation & Configuration
59 
60### [NPX](https://www.npmjs.com/package/mcp-searxng)
61 
62```json
63{
64  "mcpServers": {
65    "searxng": {
66      "command": "npx",
67      "args": ["-y", "mcp-searxng"],
68      "env": {
69        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
70      }
71    }
72  }
73}
74```
75 
76<details>
77<summary>Full Configuration Example (All Options)</summary>
78 
79```json
80{
81  "mcpServers": {
82    "searxng": {
83      "command": "npx",
84      "args": ["-y", "mcp-searxng"],
85      "env": {
86        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
87        "AUTH_USERNAME": "your_username",
88        "AUTH_PASSWORD": "your_password",
89        "USER_AGENT": "MyBot/1.0",
90        "HTTP_PROXY": "http://proxy.company.com:8080",
91        "HTTPS_PROXY": "http://proxy.company.com:8080",
92        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
93      }
94    }
95  }
96}
97```
98 
99**Note:** Mix and match environment variables as needed. All optional variables can be used independently or together.
100 
101</details>
102 
103### [NPM](https://www.npmjs.com/package/mcp-searxng)
104 
105```bash
106npm install -g mcp-searxng
107```
108 
109```json
110{
111  "mcpServers": {
112    "searxng": {
113      "command": "mcp-searxng",
114      "env": {
115        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
116      }
117    }
118  }
119}
120```
121 
122<details>
123<summary>Full Configuration Example (All Options)</summary>
124 
125```json
126{
127  "mcpServers": {
128    "searxng": {
129      "command": "mcp-searxng",
130      "env": {
131        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
132        "AUTH_USERNAME": "your_username",
133        "AUTH_PASSWORD": "your_password",
134        "USER_AGENT": "MyBot/1.0",
135        "HTTP_PROXY": "http://proxy.company.com:8080",
136        "HTTPS_PROXY": "http://proxy.company.com:8080",
137        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
138      }
139    }
140  }
141}
142```
143 
144</details>
145 
146### Docker
147 
148#### Using [Pre-built Image from Docker Hub](https://hub.docker.com/r/isokoliuk/mcp-searxng)
149 
150```bash
151docker pull isokoliuk/mcp-searxng:latest
152```
153 
154```json
155{
156  "mcpServers": {
157    "searxng": {
158      "command": "docker",
159      "args": [
160        "run", "-i", "--rm",
161        "-e", "SEARXNG_URL",
162        "isokoliuk/mcp-searxng:latest"
163      ],
164      "env": {
165        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
166      }
167    }
168  }
169}
170```
171 
172<details>
173<summary>Full Configuration Example (All Options)</summary>
174 
175```json
176{
177  "mcpServers": {
178    "searxng": {
179      "command": "docker",
180      "args": [
181        "run", "-i", "--rm",
182        "-e", "SEARXNG_URL",
183        "-e", "AUTH_USERNAME",
184        "-e", "AUTH_PASSWORD",
185        "-e", "USER_AGENT",
186        "-e", "HTTP_PROXY",
187        "-e", "HTTPS_PROXY",
188        "-e", "NO_PROXY",
189        "isokoliuk/mcp-searxng:latest"
190      ],
191      "env": {
192        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
193        "AUTH_USERNAME": "your_username",
194        "AUTH_PASSWORD": "your_password",
195        "USER_AGENT": "MyBot/1.0",
196        "HTTP_PROXY": "http://proxy.company.com:8080",
197        "HTTPS_PROXY": "http://proxy.company.com:8080",
198        "NO_PROXY": "localhost,127.0.0.1,.local,.internal"
199      }
200    }
201  }
202}
203```
204 
205**Note:** Add only the `-e` flags and env variables you need.
206 
207</details>
208 
209#### Build Locally
210 
211```bash
212docker build -t mcp-searxng:latest -f Dockerfile .
213```
214 
215Use the same configuration as above, replacing `isokoliuk/mcp-searxng:latest` with `mcp-searxng:latest`.
216 
217#### Docker Compose
218 
219Create a `docker-compose.yml` file:
220 
221```yaml
222services:
223  mcp-searxng:
224    image: isokoliuk/mcp-searxng:latest
225    stdin_open: true
226    environment:
227      - SEARXNG_URL=YOUR_SEARXNG_INSTANCE_URL
228      # Add any optional variables as needed:
229      # - AUTH_USERNAME=your_username
230      # - AUTH_PASSWORD=your_password
231      # - USER_AGENT=MyBot/1.0
232      # - HTTP_PROXY=http://proxy.company.com:8080
233      # - HTTPS_PROXY=http://proxy.company.com:8080
234      # - NO_PROXY=localhost,127.0.0.1,.local,.internal
235```
236 
237Then configure your MCP client:
238 
239```json
240{
241  "mcpServers": {
242    "searxng": {
243      "command": "docker-compose",
244      "args": ["run", "--rm", "mcp-searxng"]
245    }
246  }
247}
248```
249 
250### HTTP Transport (Optional)
251 
252The server supports both STDIO (default) and HTTP transports. Set `MCP_HTTP_PORT` to enable HTTP mode.
253 
254```json
255{
256  "mcpServers": {
257    "searxng-http": {
258      "command": "mcp-searxng",
259      "env": {
260        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
261        "MCP_HTTP_PORT": "3000"
262      }
263    }
264  }
265}
266```
267 
268**HTTP Endpoints:**
269- **MCP Protocol**: `POST/GET/DELETE /mcp` 
270- **Health Check**: `GET /health`
271 
272**Testing:**
273```bash
274MCP_HTTP_PORT=3000 SEARXNG_URL=http://localhost:8080 mcp-searxng
275curl http://localhost:3000/health
276```
277 
278## Running evals
279 
280```bash
281SEARXNG_URL=YOUR_URL OPENAI_API_KEY=your-key npx mcp-eval evals.ts src/index.ts
282```
283 
284## For Developers
285 
286### Contributing
287 
288We welcome contributions! Follow these guidelines:
289 
290**Coding Standards:**
291- Use TypeScript with strict type safety
292- Follow existing error handling patterns
293- Write concise, informative error messages
294- Include unit tests for new functionality
295- Maintain 90%+ test coverage
296- Test with MCP inspector before submitting
297- Run evals to verify functionality
298 
299**Workflow:**
300 
3011. **Fork and clone:**
302   ```bash
303   git clone https://github.com/YOUR_USERNAME/mcp-searxng.git
304   cd mcp-searxng
305   git remote add upstream https://github.com/ihor-sokoliuk/mcp-searxng.git
306   ```
307 
3082. **Setup:**
309   ```bash
310   npm install
311   npm run watch  # Development mode with file watching
312   ```
313 
3143. **Development:**
315   ```bash
316   git checkout -b feature/your-feature-name
317   # Make changes in src/
318   npm run build
319   npm test
320   npm run test:coverage
321   npm run inspector
322   ```
323 
3244. **Submit:**
325   ```bash
326   git commit -m "feat: description"
327   git push origin feature/your-feature-name
328   # Create PR on GitHub
329   ```
330 
331### Testing
332 
333```bash
334npm test                    # Run all tests
335npm run test:coverage      # Generate coverage report
336npm run test:watch         # Watch mode
337```
338 
339**Coverage:** 100% success rate with comprehensive unit tests covering error handling, types, proxy configs, resources, and logging.
340 
341## License
342 
343This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
344