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.
Badge for your README
Markdown
[](/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
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)
- # π OneSearch MCP Server: Web Search, URL Discovery, Scraper & Content Prep
- 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.
- ## Features
- - Web search, scrape, discover URLs, and preprocess content from websites.
- - Support multiple search engines and web scrapers: **SearXNG**, **Tavily**, **DuckDuckGo**, **Bing**, **Google**, **Zhipu (ζΊθ°±)**, **Exa**, **Bocha (εζ₯)**, **You.com**, etc.
- - **Local web search** (browser search), support multiple search engines: **Bing**, **Google**, **Baidu**, **Sogou**, etc.
- - Use `agent-browser` for browser automation.
- - Free, no API keys required.
- - **Enabled tools:** `one_search`, `one_scrape`, `one_map`, `one_extract`
- ## Current Tool Surface
- - `one_search`
- - Returns search results from the configured provider.
- - `one_map`
- - Discovers links from a starting URL by loading the page in the browser and extracting links from its HTML.
- - Supported input fields: `url`, `search`, `includeSubdomains`, `limit`.
- - This is not a sitemap crawler; removed fields such as `ignoreSitemap` and `sitemapOnly` are rejected at the schema boundary.
- - `one_scrape`
- - Scrapes one page and returns content selected by `formats`.
- - Supported input fields: `url`, `formats`, `waitFor`, `timeout`, `skipTlsVerification`, `allowExecuteJavascript`, `actions`.
- - Supported formats: `markdown`, `html`, `rawHtml`, `links`, `screenshot`, `screenshot@fullPage`.
- - Supported bounded pre-scrape actions: `wait`, `click`, `write`, `press`, `scroll`.
- - Advanced pre-scrape action: `executeJavascript`. If `actions` contains `executeJavascript`, you must set `allowExecuteJavascript: true`.
- - `actions` run serially before content capture and fail fast on the first action error.
- - Removed fields such as `onlyMainContent`, `extract`, and `location` are rejected at the schema boundary.
- - `one_extract`
- - Accepts only `urls` and returns preprocessed text blocks for downstream tools or models.
- ## Migration from v1.1.0 and Earlier
- **Breaking Changes in v1.1.0:**
- - **Firecrawl Removed**: The Firecrawl integration has been removed in favor of `agent-browser`, which provides similar functionality without requiring external API services.
- - **New Browser Requirement**: You must install Chromium browser (see Prerequisites section).
- - **Environment Variables**: `FIRECRAWL_API_URL` and `FIRECRAWL_API_KEY` are no longer used.
- **What Changed:**
- - `one_scrape` and `one_map` now use `agent-browser` instead of Firecrawl
- - `one_extract` now preprocesses multi-URL page content for downstream analysis instead of performing built-in LLM extraction
- - All browser-based operations are now handled locally, providing better privacy and no API costs
- **Migration Steps:**
- 1. Install Chromium browser (see Prerequisites)
- 2. Remove `FIRECRAWL_API_URL` and `FIRECRAWL_API_KEY` from your environment variables
- 3. Update to the latest version: `npm install -g one-search-mcp@latest`
- ## Prerequisites
- **Browser Requirement**: This server uses `agent-browser` for web scraping and local search, which requires a Chromium-based browser.
- **Good News**: The server will automatically detect and use browsers already installed on your system:
- - β Google Chrome
- - β Microsoft Edge
- - β Chromium
- - β Google Chrome Canary
- **If you don't have any of these browsers installed**, you can:
- ```bash
- # Option 1: Install Google Chrome (Recommended)
- # Download from: https://www.google.com/chrome/
- # Option 2: Install Microsoft Edge
- # Download from: https://www.microsoft.com/edge
- # Option 3: Install Chromium via agent-browser
- npx agent-browser install
- # Option 4: Install Chromium directly
- # Download from: https://www.chromium.org/getting-involved/download-chromium/
- ```
- ## Installation
- ### Using Claude Code CLI (Recommended)
- ```bash
- # 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
- ```bash
- # 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.
- ```bash
- # 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:**
- ```bash
- # 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:**
- ```json
- {
- "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:**
- ```json
- {
- "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"
- ]
- }
- }
- }
- ```
- ## Environment Variables
- ### Search Provider
- - **SEARCH_PROVIDER** (Optional): The search provider to use, supports `searxng`, `duckduckgo`, `bing`, `tavily`, `google`, `zhipu`, `exa`, `bocha`, `ydc`, `local`, default is `local`.
- - **SEARCH_API_URL** (Optional): The URL of the SearxNG API, or Google Custom Search Engine ID for `google`.
- - **SEARCH_API_KEY** (Optional): The API key for the search provider, required for `tavily`, `bing`, `google`, `zhipu`, `exa`, `bocha`.
- - **YDC_API_KEY** (Optional): You.com API key for `SEARCH_PROVIDER=ydc`.
- ```ts
- // supported search providers
- export type SearchProvider = 'searxng' | 'duckduckgo' | 'bing' | 'tavily' | 'google' | 'zhipu' | 'exa' | 'bocha' | 'ydc' | 'local';
- ```
- ### Browser Network Security
- - **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`.
- 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.
- ### Search Provider Configuration
- | Provider | API Key Required | API URL Required | Notes |
- |----------|-----------------|------------------|-------|
- | `local` | No | No | Free, uses browser automation |
- | `duckduckgo` | No | No | Free, no API key needed |
- | `searxng` | Optional | Yes | Self-hosted meta search engine |
- | `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) |
- | `tavily` | Yes | No | [Tavily API](https://tavily.com/) |
- | `google` | Yes | Yes (Search Engine ID) | [Google Custom Search](https://developers.google.com/custom-search/v1/overview) |
- | `zhipu` | Yes | No | [ζΊθ°± AI](https://bigmodel.cn/dev/api/search-tool/web-search) |
- | `exa` | Yes | No | [Exa AI](https://exa.ai/) |
- | `bocha` | Yes | No | [εζ₯ AI](https://open.bochaai.com/) |
- | `ydc` | Yes | No | [You.com Search](https://you.com/platform) |
- ## Configuration for Other MCP Clients
- ### Claude Desktop
- Add to your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- ```json
- {
- "mcpServers": {
- "one-search-mcp": {
- "command": "npx",
- "args": ["-y", "one-search-mcp"],
- "env": {
- "SEARCH_PROVIDER": "local"
- }
- }
- }
- }
- ```
- ### Cursor
- Add to your `mcp.json` file:
- ```json
- {
- "mcpServers": {
- "one-search-mcp": {
- "command": "npx",
- "args": ["-y", "one-search-mcp"],
- "env": {
- "SEARCH_PROVIDER": "local"
- }
- }
- }
- }
- ```
- ### Windsurf
- Add to your `./codeium/windsurf/model_config.json` file:
- ```json
- {
- "mcpServers": {
- "one-search-mcp": {
- "command": "npx",
- "args": ["-y", "one-search-mcp"],
- "env": {
- "SEARCH_PROVIDER": "local"
- }
- }
- }
- }
- ```
- ## Self-hosting SearXNG (Optional)
- If you want to use SearXNG as your search provider, you can deploy it locally using Docker:
- **Prerequisites:**
- - Docker installed and running (version 20.10.0 or higher)
- - At least 4GB of RAM available
- **Quick Start:**
- ```bash
- # Clone SearXNG Docker repository
- git clone https://github.com/searxng/searxng-docker.git
- cd searxng-docker
- # Start SearXNG
- docker compose up -d
- ```
- After deployment, SearXNG will be available at `http://127.0.0.1:8080` by default.
- **Configure OneSearch to use SearXNG:**
- ```bash
- # Set environment variables
- export SEARCH_PROVIDER=searxng
- export SEARCH_API_URL=http://127.0.0.1:8080
- ```
- For more details, see the [official SearXNG Docker documentation](https://github.com/searxng/searxng-docker).
- ## Troubleshooting
- ### Browser not found error
- 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:
- - **Google Chrome**: <https://www.google.com/chrome/>
- - **Microsoft Edge**: <https://www.microsoft.com/edge>
- - **Chromium**: <https://www.chromium.org/getting-involved/download-chromium/>
- Or install via agent-browser:
- ```bash
- npx agent-browser install
- ```
- ## License
- MIT License - see [LICENSE](./LICENSE) file for details.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itβs helped, pass it on.