Skip to content
Back to search

web-search-mcp

A simple, locally hosted Web Search MCP server for use with Local LLMs

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mrkrsl--web-search-mcp/badge.svg)](/listings/mrkrsl--web-search-mcp)

HTML

<a href="/listings/mrkrsl--web-search-mcp"><img src="/api/listings/mrkrsl--web-search-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Requirements:** - Node.js 18.0.0 or higher - npm 8.0.0 or higher

1. Download the latest release zip file from the [Releases page](https://github.com/mrkrsl/web-search-mcp/releases) 2. Extract the zip file to a location on your system (e.g., `~/mcp-servers/web-search-mcp/`) 3. **Open a terminal in the extracted folder and run:**

   npm install
   npx playwright install
   npm run build

This will create a `node_modules` folder with all required dependencies, install Playwright browsers, and build the project.

**Note:** You must run `npm install` in the root of the extracted folder (not in `dist/`). 4. Configure your `mcp.json` to point to the extracted `dist/index.js` file:

{
  "mcpServers": {
    "web-search": {
      "command": "node",
      "args": ["/path/to/extracted/web-search-mcp/dist/index.js"]
    }
  }
}

**Example paths:** - macOS/Linux: `~/mcp-servers/web-search-mcp/dist/index.js` - Windows: `C:\\mcp-servers\\web-search-mcp\\dist\\index.js`

In LibreChat, you can include the MCP server in the librechat.yaml. If you are running LibreChat in Docker, you must first mount your local directory in docker-compose.override.yml.

in `docker-compose.override.yml`:

services:
  api:
    volumes:
    - type: bind
      source: /path/to/your/mcp/directory
      target: /app/mcp

in `librechat.yaml`:

mcpServers:
  web-search:
    type: stdio
    command: node
    args:
    - /app/mcp/web-search-mcp/dist/index.js
    serverInstructions: true

**Troubleshooting:** - If `npm install` fails, try updating Node.js to version 18+ and npm to version 8+ - If `npm run build` fails, ensure you have the latest Node.js version installed - For older Node.js versions, you may need to use an older release of this project - **Content Length Issues:** If you experience odd behavior due to content length limits, try setting `"MAX_CONTENT_LENGTH": "10000"`, or another value, in your `mcp.json` environment variables:

{
  "mcpServers": {
    "web-search": {
      "command": "node",
      "args": ["/path/to/web-search-mcp/dist/index.js"],
      "env": {
        "MAX_CONTENT_LENGTH": "10000",
        "BROWSER_HEADLESS": "true",
        "MAX_BROWSERS": "3",
        "BROWSER_FALLBACK_THRESHOLD": "3"
      }
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 274 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Web Search MCP Server for use with Local LLMs
  2. A TypeScript MCP (Model Context Protocol) server that provides comprehensive web search capabilities using direct connections (no API keys required) with multiple tools for different use cases.
  3. ## Features
  4. - **Multi-Engine Web Search**: Prioritises Bing > Brave > DuckDuckGo for optimal reliability and performance
  5. - **Full Page Content Extraction**: Fetches and extracts complete page content from search results
  6. - **Multiple Search Tools**: Three specialised tools for different use cases
  7. - **Smart Request Strategy**: Switches between playwright browesrs and fast axios requests to ensure results are returned
  8. - **Concurrent Processing**: Extracts content from multiple pages simultaneously
  9. ## How It Works
  10. The server provides three specialised tools for different web search needs:
  11. ### 1. `full-web-search` (Main Tool)
  12. When a comprehensive search is requested, the server uses an **optimised search strategy**:
  13. 1. **Browser-based Bing Search** - Primary method using dedicated Chromium instance
  14. 2. **Browser-based Brave Search** - Secondary option using dedicated Firefox instance
  15. 3. **Axios DuckDuckGo Search** - Final fallback using traditional HTTP
  16. 4. **Dedicated browser isolation**: Each search engine gets its own browser instance with automatic cleanup
  17. 5. **Content extraction**: Tries axios first, then falls back to browser with human behavior simulation
  18. 6. **Concurrent processing**: Extracts content from multiple pages simultaneously with timeout protection
  19. 7. **HTTP/2 error recovery**: Automatically falls back to HTTP/1.1 when protocol errors occur
  20. ### 2. `get-web-search-summaries` (Lightweight Alternative)
  21. For quick search results without full content extraction:
  22. 1. Performs the same optimised multi-engine search as `full-web-search`
  23. 2. Returns only the search result snippets/descriptions
  24. 3. Does not follow links to extract full page content
  25. ### 3. `get-single-web-page-content` (Utility Tool)
  26. For extracting content from a specific webpage:
  27. 1. Takes a single URL as input
  28. 2. Follows the URL and extracts the main page content
  29. 3. Removes navigation, ads, and other non-content elements
  30. ## Compatibility
  31. This MCP server has been developed and tested with **LM Studio** and **LibreChat**. It has not been tested with other MCP clients.
  32. ### Model Compatibility
  33. **Important:** Prioritise using more recent models designated for tool use.
  34. Older models (even those with tool use specified) may not work or may work erratically. This seems to be the case with Llama and Deepseek. Qwen3 and Gemma 3 currently have the best restults.
  35. - ✅ Works well with: **Qwen3**
  36. - ✅ Works well with: **Gemma 3**
  37. - ✅ Works with: **Llama 3.2**
  38. - ✅ Works with: Recent **Llama 3.1** (e.g 3.1 swallow-8B)
  39. - ✅ Works with: Recent **Deepseek R1** (e.g 0528 works)
  40. - ⚠️ May have issues with: Some versions of **Llama** and **Deepseek R1**
  41. - ❌ May not work with: Older versions of **Llama** and **Deepseek R1**
  42. ## Installation (Recommended)
  43. **Requirements:**
  44. - Node.js 18.0.0 or higher
  45. - npm 8.0.0 or higher
  46. 1. Download the latest release zip file from the [Releases page](https://github.com/mrkrsl/web-search-mcp/releases)
  47. 2. Extract the zip file to a location on your system (e.g., `~/mcp-servers/web-search-mcp/`)
  48. 3. **Open a terminal in the extracted folder and run:**
  49. ```bash
  50. npm install
  51. npx playwright install
  52. npm run build
  53. ```
  54. This will create a `node_modules` folder with all required dependencies, install Playwright browsers, and build the project.
  55. **Note:** You must run `npm install` in the root of the extracted folder (not in `dist/`).
  56. 4. Configure your `mcp.json` to point to the extracted `dist/index.js` file:
  57. ```json
  58. {
  59. "mcpServers": {
  60. "web-search": {
  61. "command": "node",
  62. "args": ["/path/to/extracted/web-search-mcp/dist/index.js"]
  63. }
  64. }
  65. }
  66. ```
  67. **Example paths:**
  68. - macOS/Linux: `~/mcp-servers/web-search-mcp/dist/index.js`
  69. - Windows: `C:\\mcp-servers\\web-search-mcp\\dist\\index.js`
  70. In LibreChat, you can include the MCP server in the librechat.yaml. If you are running LibreChat in Docker, you must first mount your local directory in docker-compose.override.yml.
  71. in `docker-compose.override.yml`:
  72. ```yaml
  73. services:
  74. api:
  75. volumes:
  76. - type: bind
  77. source: /path/to/your/mcp/directory
  78. target: /app/mcp
  79. ```
  80. in `librechat.yaml`:
  81. ```yaml
  82. mcpServers:
  83. web-search:
  84. type: stdio
  85. command: node
  86. args:
  87. - /app/mcp/web-search-mcp/dist/index.js
  88. serverInstructions: true
  89. ```
  90. **Troubleshooting:**
  91. - If `npm install` fails, try updating Node.js to version 18+ and npm to version 8+
  92. - If `npm run build` fails, ensure you have the latest Node.js version installed
  93. - For older Node.js versions, you may need to use an older release of this project
  94. - **Content Length Issues:** If you experience odd behavior due to content length limits, try setting `"MAX_CONTENT_LENGTH": "10000"`, or another value, in your `mcp.json` environment variables:
  95. ```json
  96. {
  97. "mcpServers": {
  98. "web-search": {
  99. "command": "node",
  100. "args": ["/path/to/web-search-mcp/dist/index.js"],
  101. "env": {
  102. "MAX_CONTENT_LENGTH": "10000",
  103. "BROWSER_HEADLESS": "true",
  104. "MAX_BROWSERS": "3",
  105. "BROWSER_FALLBACK_THRESHOLD": "3"
  106. }
  107. }
  108. }
  109. }
  110. ```
  111. ## Environment Variables
  112. The server supports several environment variables for configuration:
  113. - **`MAX_CONTENT_LENGTH`**: Maximum content length in characters (default: 500000)
  114. - **`DEFAULT_TIMEOUT`**: Default timeout for requests in milliseconds (default: 6000)
  115. - **`MAX_BROWSERS`**: Maximum number of browser instances to maintain (default: 3)
  116. - **`BROWSER_TYPES`**: Comma-separated list of browser types to use (default: 'chromium,firefox', options: chromium, firefox, webkit)
  117. - **`BROWSER_FALLBACK_THRESHOLD`**: Number of axios failures before using browser fallback (default: 3)
  118. ### Search Quality and Engine Selection
  119. - **`ENABLE_RELEVANCE_CHECKING`**: Enable/disable search result quality validation (default: true)
  120. - **`RELEVANCE_THRESHOLD`**: Minimum quality score for search results (0.0-1.0, default: 0.3)
  121. - **`FORCE_MULTI_ENGINE_SEARCH`**: Try all search engines and return best results (default: false)
  122. - **`DEBUG_BROWSER_LIFECYCLE`**: Enable detailed browser lifecycle logging for debugging (default: false)
  123. ## Troubleshooting
  124. ### Slow Response Times
  125. - **Optimised timeouts**: Default timeout reduced to 6 seconds with concurrent processing for faster results
  126. - **Concurrent extraction**: Content is now extracted from multiple pages simultaneously
  127. - **Reduce timeouts further**: Set `DEFAULT_TIMEOUT=4000` for even faster responses (may reduce success rate)
  128. - **Use fewer browsers**: Set `MAX_BROWSERS=1` to reduce memory usage
  129. ### Search Failures
  130. - **Check browser installation**: Run `npx playwright install` to ensure browsers are available
  131. - **Try headless mode**: Ensure `BROWSER_HEADLESS=true` (default) for server environments
  132. - **Network restrictions**: Some networks block browser automation - try different network or VPN
  133. - **HTTP/2 issues**: The server automatically handles HTTP/2 protocol errors with fallback to HTTP/1.1
  134. ### Search Quality Issues
  135. - **Enable quality checking**: Set `ENABLE_RELEVANCE_CHECKING=true` (enabled by default)
  136. - **Adjust quality threshold**: Set `RELEVANCE_THRESHOLD=0.5` for stricter quality requirements
  137. - **Force multi-engine search**: Set `FORCE_MULTI_ENGINE_SEARCH=true` to try all engines and return the best results
  138. ### Memory Usage
  139. - **Automatic cleanup**: Browsers are automatically cleaned up after each operation to prevent memory leaks
  140. - **Limit browsers**: Reduce `MAX_BROWSERS` (default: 3)
  141. - **EventEmitter warnings**: Fixed - browsers are properly closed to prevent listener accumulation
  142. ## For Development
  143. ```bash
  144. git clone https://github.com/mrkrsl/web-search-mcp.git
  145. cd web-search-mcp
  146. npm install
  147. npx playwright install
  148. npm run build
  149. ```
  150. ## Development
  151. ```bash
  152. npm run dev # Development with hot reload
  153. npm run build # Build TypeScript to JavaScript
  154. npm run lint # Run ESLint
  155. npm run format # Run Prettier
  156. ```
  157. ## MCP Tools
  158. This server provides three specialised tools for different web search needs:
  159. ### 1. `full-web-search` (Main Tool)
  160. The most comprehensive web search tool that:
  161. 1. Takes a search query and optional number of results (1-10, default 5)
  162. 2. Performs a web search (tries Bing, then Brave, then DuckDuckGo if needed)
  163. 3. Fetches full page content from each result URL with concurrent processing
  164. 4. Returns structured data with search results and extracted content
  165. 5. **Enhanced reliability**: HTTP/2 error recovery, reduced timeouts, and better error handling
  166. **Example Usage:**
  167. ```json
  168. {
  169. "name": "full-web-search",
  170. "arguments": {
  171. "query": "TypeScript MCP server",
  172. "limit": 3,
  173. "includeContent": true
  174. }
  175. }
  176. ```
  177. ### 2. `get-web-search-summaries` (Lightweight Alternative)
  178. A lightweight alternative for quick search results:
  179. 1. Takes a search query and optional number of results (1-10, default 5)
  180. 2. Performs the same optimised multi-engine search as `full-web-search`
  181. 3. Returns only search result snippets/descriptions (no content extraction)
  182. 4. Faster and more efficient for quick research
  183. **Example Usage:**
  184. ```json
  185. {
  186. "name": "get-web-search-summaries",
  187. "arguments": {
  188. "query": "TypeScript MCP server",
  189. "limit": 5
  190. }
  191. }
  192. ```
  193. ### 3. `get-single-web-page-content` (Utility Tool)
  194. A utility tool for extracting content from a specific webpage:
  195. 1. Takes a single URL as input
  196. 2. Follows the URL and extracts the main page content
  197. 3. Removes navigation, ads, and other non-content elements
  198. 4. Useful for getting detailed content from a known webpage
  199. **Example Usage:**
  200. ```json
  201. {
  202. "name": "get-single-web-page-content",
  203. "arguments": {
  204. "url": "https://example.com/article",
  205. "maxContentLength": 5000
  206. }
  207. }
  208. ```
  209. ## Standalone Usage
  210. You can also run the server directly:
  211. ```bash
  212. # If running from source
  213. npm start
  214. ```
  215. ## Documentation
  216. See [API.md](./docs/API.md) for complete technical details.
  217. ## License
  218. MIT License - see [LICENSE](./LICENSE) for details.
  219. ## Feedback
  220. This is an open source project and we welcome feedback! If you encounter any issues or have suggestions for improvements, please:
  221. - Open an issue on GitHub
  222. - Submit a pull request

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.