Skip to content
Back to search

one-search-mcp

πŸš€ OneSearch MCP Server: Web Search & Scraper & Extract, Support agent-browser, SearXNG, Tavily, DuckDuckGo, Bing, etc.

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/yokingma--one-search-mcp/badge.svg)](/listings/yokingma--one-search-mcp)

HTML

<a href="/listings/yokingma--one-search-mcp"><img src="/api/listings/yokingma--one-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.

Using Claude Code CLI (Recommended)

# Add to Claude Code with default settings (local search)
claude mcp add one-search-mcp -- npx -y one-search-mcp

# Add with custom search provider (e.g., SearXNG)
claude mcp add one-search-mcp -e SEARCH_PROVIDER=searxng -e SEARCH_API_URL=http://127.0.0.1:8080 -- npx -y one-search-mcp

# Add with Tavily API
claude mcp add one-search-mcp -e SEARCH_PROVIDER=tavily -e SEARCH_API_KEY=your_api_key -- npx -y one-search-mcp

Manual Installation

# Install globally (Optional)
npm install -g one-search-mcp

# Or run directly with npx
npx -y one-search-mcp

Local Debugging with MCP Inspector

Use the official MCP Inspector to interactively test tools, resources, and prompts against this server during local development.

# Inspect the TypeScript source entrypoint
npm run inspector

# Inspect the built server entrypoint
npm run inspector:build

# Example with explicit environment variables
ALLOW_PRIVATE_NETWORK=true SEARCH_PROVIDER=local npm run inspector

Using Docker

Docker image includes all dependencies (Chromium browser) pre-installed, no additional setup required.

**Pull the image:**

# From GitHub Container Registry
docker pull ghcr.io/yokingma/one-search-mcp:latest

# Or from Docker Hub
docker pull zacma/one-search-mcp:latest

**Configure with Claude Desktop:**

{
  "mcpServers": {
    "one-search-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/yokingma/one-search-mcp:latest"],
      "env": {
        "SEARCH_PROVIDER": "local"
      }
    }
  }
}

**With custom search provider:**

{
  "mcpServers": {
    "one-search-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEARCH_PROVIDER=tavily",
        "-e", "SEARCH_API_KEY=your_api_key",
        "ghcr.io/yokingma/one-search-mcp:latest"
      ]
    }
  }
}

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 Β· 312 lines

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

  1. # πŸš€ OneSearch MCP Server: Web Search, URL Discovery, Scraper & Content Prep
  2. A Model Context Protocol (MCP) server implementation that integrates with multiple search providers for web search, local browser search, URL discovery, and scraping capabilities with agent-browser.
  3. ## Features
  4. - Web search, scrape, discover URLs, and preprocess content from websites.
  5. - Support multiple search engines and web scrapers: **SearXNG**, **Tavily**, **DuckDuckGo**, **Bing**, **Google**, **Zhipu (ζ™Ίθ°±)**, **Exa**, **Bocha (博ζŸ₯)**, **You.com**, etc.
  6. - **Local web search** (browser search), support multiple search engines: **Bing**, **Google**, **Baidu**, **Sogou**, etc.
  7. - Use `agent-browser` for browser automation.
  8. - Free, no API keys required.
  9. - **Enabled tools:** `one_search`, `one_scrape`, `one_map`, `one_extract`
  10. ## Current Tool Surface
  11. - `one_search`
  12. - Returns search results from the configured provider.
  13. - `one_map`
  14. - Discovers links from a starting URL by loading the page in the browser and extracting links from its HTML.
  15. - Supported input fields: `url`, `search`, `includeSubdomains`, `limit`.
  16. - This is not a sitemap crawler; removed fields such as `ignoreSitemap` and `sitemapOnly` are rejected at the schema boundary.
  17. - `one_scrape`
  18. - Scrapes one page and returns content selected by `formats`.
  19. - Supported input fields: `url`, `formats`, `waitFor`, `timeout`, `skipTlsVerification`, `allowExecuteJavascript`, `actions`.
  20. - Supported formats: `markdown`, `html`, `rawHtml`, `links`, `screenshot`, `screenshot@fullPage`.
  21. - Supported bounded pre-scrape actions: `wait`, `click`, `write`, `press`, `scroll`.
  22. - Advanced pre-scrape action: `executeJavascript`. If `actions` contains `executeJavascript`, you must set `allowExecuteJavascript: true`.
  23. - `actions` run serially before content capture and fail fast on the first action error.
  24. - Removed fields such as `onlyMainContent`, `extract`, and `location` are rejected at the schema boundary.
  25. - `one_extract`
  26. - Accepts only `urls` and returns preprocessed text blocks for downstream tools or models.
  27. ## Migration from v1.1.0 and Earlier
  28. **Breaking Changes in v1.1.0:**
  29. - **Firecrawl Removed**: The Firecrawl integration has been removed in favor of `agent-browser`, which provides similar functionality without requiring external API services.
  30. - **New Browser Requirement**: You must install Chromium browser (see Prerequisites section).
  31. - **Environment Variables**: `FIRECRAWL_API_URL` and `FIRECRAWL_API_KEY` are no longer used.
  32. **What Changed:**
  33. - `one_scrape` and `one_map` now use `agent-browser` instead of Firecrawl
  34. - `one_extract` now preprocesses multi-URL page content for downstream analysis instead of performing built-in LLM extraction
  35. - All browser-based operations are now handled locally, providing better privacy and no API costs
  36. **Migration Steps:**
  37. 1. Install Chromium browser (see Prerequisites)
  38. 2. Remove `FIRECRAWL_API_URL` and `FIRECRAWL_API_KEY` from your environment variables
  39. 3. Update to the latest version: `npm install -g one-search-mcp@latest`
  40. ## Prerequisites
  41. **Browser Requirement**: This server uses `agent-browser` for web scraping and local search, which requires a Chromium-based browser.
  42. **Good News**: The server will automatically detect and use browsers already installed on your system:
  43. - βœ… Google Chrome
  44. - βœ… Microsoft Edge
  45. - βœ… Chromium
  46. - βœ… Google Chrome Canary
  47. **If you don't have any of these browsers installed**, you can:
  48. ```bash
  49. # Option 1: Install Google Chrome (Recommended)
  50. # Download from: https://www.google.com/chrome/
  51. # Option 2: Install Microsoft Edge
  52. # Download from: https://www.microsoft.com/edge
  53. # Option 3: Install Chromium via agent-browser
  54. npx agent-browser install
  55. # Option 4: Install Chromium directly
  56. # Download from: https://www.chromium.org/getting-involved/download-chromium/
  57. ```
  58. ## Installation
  59. ### Using Claude Code CLI (Recommended)
  60. ```bash
  61. # Add to Claude Code with default settings (local search)
  62. claude mcp add one-search-mcp -- npx -y one-search-mcp
  63. # Add with custom search provider (e.g., SearXNG)
  64. claude mcp add one-search-mcp -e SEARCH_PROVIDER=searxng -e SEARCH_API_URL=http://127.0.0.1:8080 -- npx -y one-search-mcp
  65. # Add with Tavily API
  66. claude mcp add one-search-mcp -e SEARCH_PROVIDER=tavily -e SEARCH_API_KEY=your_api_key -- npx -y one-search-mcp
  67. ```
  68. ### Manual Installation
  69. ```bash
  70. # Install globally (Optional)
  71. npm install -g one-search-mcp
  72. # Or run directly with npx
  73. npx -y one-search-mcp
  74. ```
  75. ### Local Debugging with MCP Inspector
  76. Use the official MCP Inspector to interactively test tools, resources, and prompts against this server during local development.
  77. ```bash
  78. # Inspect the TypeScript source entrypoint
  79. npm run inspector
  80. # Inspect the built server entrypoint
  81. npm run inspector:build
  82. # Example with explicit environment variables
  83. ALLOW_PRIVATE_NETWORK=true SEARCH_PROVIDER=local npm run inspector
  84. ```
  85. ### Using Docker
  86. Docker image includes all dependencies (Chromium browser) pre-installed, no additional setup required.
  87. **Pull the image:**
  88. ```bash
  89. # From GitHub Container Registry
  90. docker pull ghcr.io/yokingma/one-search-mcp:latest
  91. # Or from Docker Hub
  92. docker pull zacma/one-search-mcp:latest
  93. ```
  94. **Configure with Claude Desktop:**
  95. ```json
  96. {
  97. "mcpServers": {
  98. "one-search-mcp": {
  99. "command": "docker",
  100. "args": ["run", "-i", "--rm", "ghcr.io/yokingma/one-search-mcp:latest"],
  101. "env": {
  102. "SEARCH_PROVIDER": "local"
  103. }
  104. }
  105. }
  106. }
  107. ```
  108. **With custom search provider:**
  109. ```json
  110. {
  111. "mcpServers": {
  112. "one-search-mcp": {
  113. "command": "docker",
  114. "args": [
  115. "run", "-i", "--rm",
  116. "-e", "SEARCH_PROVIDER=tavily",
  117. "-e", "SEARCH_API_KEY=your_api_key",
  118. "ghcr.io/yokingma/one-search-mcp:latest"
  119. ]
  120. }
  121. }
  122. }
  123. ```
  124. ## Environment Variables
  125. ### Search Provider
  126. - **SEARCH_PROVIDER** (Optional): The search provider to use, supports `searxng`, `duckduckgo`, `bing`, `tavily`, `google`, `zhipu`, `exa`, `bocha`, `ydc`, `local`, default is `local`.
  127. - **SEARCH_API_URL** (Optional): The URL of the SearxNG API, or Google Custom Search Engine ID for `google`.
  128. - **SEARCH_API_KEY** (Optional): The API key for the search provider, required for `tavily`, `bing`, `google`, `zhipu`, `exa`, `bocha`.
  129. - **YDC_API_KEY** (Optional): You.com API key for `SEARCH_PROVIDER=ydc`.
  130. ```ts
  131. // supported search providers
  132. export type SearchProvider = 'searxng' | 'duckduckgo' | 'bing' | 'tavily' | 'google' | 'zhipu' | 'exa' | 'bocha' | 'ydc' | 'local';
  133. ```
  134. ### Browser Network Security
  135. - **ALLOW_PRIVATE_NETWORK** (Optional): Set to `true` to allow browser-backed tools (`one_scrape`, `one_map`, `one_extract`) to access private, loopback, and link-local network targets. Defaults to `false`.
  136. Use `ALLOW_PRIVATE_NETWORK=true` only in trusted deployments. When enabled, prompt injection or untrusted tool inputs can make the MCP process fetch internal services that are otherwise blocked by default.
  137. ### Search Provider Configuration
  138. | Provider | API Key Required | API URL Required | Notes |
  139. |----------|-----------------|------------------|-------|
  140. | `local` | No | No | Free, uses browser automation |
  141. | `duckduckgo` | No | No | Free, no API key needed |
  142. | `searxng` | Optional | Yes | Self-hosted meta search engine |
  143. | `bing` | Yes | No | [Bing Search API](https://learn.microsoft.com/en-us/previous-versions/bing/search-apis/bing-web-search/create-bing-search-service-resource) |
  144. | `tavily` | Yes | No | [Tavily API](https://tavily.com/) |
  145. | `google` | Yes | Yes (Search Engine ID) | [Google Custom Search](https://developers.google.com/custom-search/v1/overview) |
  146. | `zhipu` | Yes | No | [ζ™Ίθ°± AI](https://bigmodel.cn/dev/api/search-tool/web-search) |
  147. | `exa` | Yes | No | [Exa AI](https://exa.ai/) |
  148. | `bocha` | Yes | No | [博ζŸ₯ AI](https://open.bochaai.com/) |
  149. | `ydc` | Yes | No | [You.com Search](https://you.com/platform) |
  150. ## Configuration for Other MCP Clients
  151. ### Claude Desktop
  152. Add to your Claude Desktop configuration file:
  153. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  154. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  155. ```json
  156. {
  157. "mcpServers": {
  158. "one-search-mcp": {
  159. "command": "npx",
  160. "args": ["-y", "one-search-mcp"],
  161. "env": {
  162. "SEARCH_PROVIDER": "local"
  163. }
  164. }
  165. }
  166. }
  167. ```
  168. ### Cursor
  169. Add to your `mcp.json` file:
  170. ```json
  171. {
  172. "mcpServers": {
  173. "one-search-mcp": {
  174. "command": "npx",
  175. "args": ["-y", "one-search-mcp"],
  176. "env": {
  177. "SEARCH_PROVIDER": "local"
  178. }
  179. }
  180. }
  181. }
  182. ```
  183. ### Windsurf
  184. Add to your `./codeium/windsurf/model_config.json` file:
  185. ```json
  186. {
  187. "mcpServers": {
  188. "one-search-mcp": {
  189. "command": "npx",
  190. "args": ["-y", "one-search-mcp"],
  191. "env": {
  192. "SEARCH_PROVIDER": "local"
  193. }
  194. }
  195. }
  196. }
  197. ```
  198. ## Self-hosting SearXNG (Optional)
  199. If you want to use SearXNG as your search provider, you can deploy it locally using Docker:
  200. **Prerequisites:**
  201. - Docker installed and running (version 20.10.0 or higher)
  202. - At least 4GB of RAM available
  203. **Quick Start:**
  204. ```bash
  205. # Clone SearXNG Docker repository
  206. git clone https://github.com/searxng/searxng-docker.git
  207. cd searxng-docker
  208. # Start SearXNG
  209. docker compose up -d
  210. ```
  211. After deployment, SearXNG will be available at `http://127.0.0.1:8080` by default.
  212. **Configure OneSearch to use SearXNG:**
  213. ```bash
  214. # Set environment variables
  215. export SEARCH_PROVIDER=searxng
  216. export SEARCH_API_URL=http://127.0.0.1:8080
  217. ```
  218. For more details, see the [official SearXNG Docker documentation](https://github.com/searxng/searxng-docker).
  219. ## Troubleshooting
  220. ### Browser not found error
  221. If you see an error like "Browser not found", the server couldn't detect any installed Chromium-based browser. Please install one of the following:
  222. - **Google Chrome**: <https://www.google.com/chrome/>
  223. - **Microsoft Edge**: <https://www.microsoft.com/edge>
  224. - **Chromium**: <https://www.chromium.org/getting-involved/download-chromium/>
  225. Or install via agent-browser:
  226. ```bash
  227. npx agent-browser install
  228. ```
  229. ## License
  230. MIT License - see [LICENSE](./LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

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