🚀 OneSearch MCP Server: Web Search & Crawl & Scraper & Extract

🚀 OneSearch MCP 服务：网页搜索、URL 发现、网页抓取与内容准备

一种 Model Context Protocol (MCP) 服务实现，可集成多个搜索提供商，提供网页搜索、本地浏览器搜索、URL 发现和通过 agent-browser 进行网页抓取的功能。

功能

• 搜索网页、抓取网页、发现 URL，并对网站内容进行预处理。
• 支持多个搜索引擎和网页抓取工具：SearXNG、Tavily、DuckDuckGo、Bing、Google、Zhipu (智谱)、Exa、Bocha (博查)、You.com 等。
• 本地网页搜索（浏览器搜索），支持多个搜索引擎：Bing、Google、Baidu、Sogou 等。
  • 使用 agent-browser 进行浏览器自动化。
  • 免费，无需 API 密钥。
• 已启用的工具：one_search、one_scrape、one_map、one_extract

当前工具接口

• one_search
  • 返回所配置提供商的搜索结果。
• one_map
  • 在浏览器中加载页面并从其 HTML 中提取链接，从起始 URL 发现链接。
  • 支持的输入字段：url、search、includeSubdomains、limit。
  • 这不是站点地图爬虫；已移除的字段（例如 ignoreSitemap 和 sitemapOnly）会在 schema 边界处被拒绝。
• one_scrape
  • 抓取单个页面，并根据 formats 选择返回的内容。
  • 支持的输入字段：url、formats、waitFor、timeout、skipTlsVerification、allowExecuteJavascript、actions。
  • 支持的格式：markdown、html、rawHtml、links、screenshot、screenshot@fullPage。
  • 支持的有限抓取前操作：wait、click、write、press、scroll。
  • 高级抓取前操作：executeJavascript。如果 actions 中包含 executeJavascript，必须设置 allowExecuteJavascript: true。
  • actions 会在内容捕获前按顺序运行，遇到第一个操作错误时立即失败。
  • 已移除的字段（例如 onlyMainContent、extract 和 location）会在 schema 边界处被拒绝。
• one_extract
  • 仅接受 urls，并返回供下游工具或模型使用的预处理文本块。

从 v1.1.0 及更早版本迁移

v1.1.0 中的重大变更：

• 移除 Firecrawl：已移除 Firecrawl 集成，改用 agent-browser。它能提供类似功能，且无需外部 API 服务。
• 新增浏览器要求：必须安装 Chromium 浏览器（请参阅“先决条件”部分）。
• 环境变量：不再使用 FIRECRAWL_API_URL 和 FIRECRAWL_API_KEY。

变更内容：

• one_scrape 和 one_map 现在使用 agent-browser，而非 Firecrawl
• one_extract 现在会预处理多个 URL 的页面内容，供下游分析使用，而不再执行内置的大模型提取
• 所有基于浏览器的操作现在都在本地处理，隐私保护更佳，且无需支付 API 费用

迁移步骤：

1. 安装 Chromium 浏览器（请参阅“先决条件”）
2. 从环境变量中移除 FIRECRAWL_API_URL 和 FIRECRAWL_API_KEY
3. 更新到最新版本：npm install -g one-search-mcp@latest

先决条件

浏览器要求：此服务使用 agent-browser 进行网页抓取和本地搜索，因此需要基于 Chromium 的浏览器。

好消息：服务会自动检测并使用系统上已安装的浏览器：

• ✅ Google Chrome
• ✅ Microsoft Edge
• ✅ Chromium
• ✅ Google Chrome Canary

如果未安装上述任何浏览器，你可以：

# 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/

安装

使用 Claude Code CLI（推荐）

# 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

手动安装

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

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

使用 MCP Inspector 在本地调试

在本地开发期间，使用官方 MCP Inspector 与此服务交互，测试工具、资源和提示词。

# 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

使用 Docker

Docker 镜像已预装所有依赖项（Chromium 浏览器），无需额外设置。

拉取镜像：

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

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

配置 Claude Desktop：

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

使用自定义搜索提供商：

{
  "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"
      ]
    }
  }
}

环境变量

搜索提供商

• SEARCH_PROVIDER（可选）：要使用的搜索提供商，支持 searxng、duckduckgo、bing、tavily、google、zhipu、exa、bocha、ydc、local，默认为 local。
• SEARCH_API_URL（可选）：SearxNG API 的 URL，或 google 的 Google Custom Search Engine ID。
• SEARCH_API_KEY（可选）：搜索提供商的 API 密钥；tavily、bing、google、zhipu、exa、bocha 必填。
• YDC_API_KEY（可选）：SEARCH_PROVIDER=ydc 时使用的 You.com API 密钥。

// supported search providers
export type SearchProvider = 'searxng' | 'duckduckgo' | 'bing' | 'tavily' | 'google' | 'zhipu' | 'exa' | 'bocha' | 'ydc' | 'local';

浏览器网络安全

• ALLOW_PRIVATE_NETWORK（可选）：设置为 true 后，允许基于浏览器的工具（one_scrape、one_map、one_extract）访问专用网络、环回网络和链路本地网络目标。默认值为 false。

仅在可信部署中使用 ALLOW_PRIVATE_NETWORK=true。启用后，提示词注入或不可信的工具输入可能会导致 MCP 进程获取默认情况下会被阻止的内部服务。

搜索提供商配置

提供商	是否需要 API 密钥	是否需要 API URL	备注
local	否	否	免费，使用浏览器自动化
duckduckgo	否	否	免费，无需 API 密钥
searxng	可选	是	可自托管的元搜索引擎
bing	是	否	Bing 搜索 API
tavily	是	否	Tavily API
google	是	是（Search Engine ID）	Google Custom Search
zhipu	是	否	智谱 AI
exa	是	否	Exa AI
bocha	是	否	博查 AI
ydc	是	否	You.com 搜索

其他 MCP 客户端的配置

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "one-search-mcp": {
      "command": "npx",
      "args": ["-y", "one-search-mcp"],
      "env": {
        "SEARCH_PROVIDER": "local"
      }
    }
  }
}

Cursor

将以下内容添加到 mcp.json 文件中：

{
  "mcpServers": {
    "one-search-mcp": {
      "command": "npx",
      "args": ["-y", "one-search-mcp"],
      "env": {
        "SEARCH_PROVIDER": "local"
      }
    }
  }
}

Windsurf

将以下内容添加到 ./codeium/windsurf/model_config.json 文件中：

{
  "mcpServers": {
    "one-search-mcp": {
      "command": "npx",
      "args": ["-y", "one-search-mcp"],
      "env": {
        "SEARCH_PROVIDER": "local"
      }
    }
  }
}

自托管 SearXNG（可选）

如果想使用 SearXNG 作为搜索提供商，可以使用 Docker 在本地部署：

前提条件：

• 已安装并运行 Docker（版本 20.10.0 或更高）
• 至少有 4GB 可用内存

快速开始：

# Clone SearXNG Docker repository
git clone https://github.com/searxng/searxng-docker.git
cd searxng-docker

# Start SearXNG
docker compose up -d

部署后，SearXNG 默认可通过 http://127.0.0.1:8080 访问。

配置 OneSearch 使用 SearXNG：

# Set environment variables
export SEARCH_PROVIDER=searxng
export SEARCH_API_URL=http://127.0.0.1:8080

更多详情请参阅 SearXNG 官方 Docker 文档。

故障排除

找不到浏览器错误

如果看到类似“Browser not found”的错误，说明服务未能检测到已安装的 Chromium 内核浏览器。请安装以下浏览器之一：

• Google Chrome：https://www.google.com/chrome/
• Microsoft Edge：https://www.microsoft.com/edge
• Chromium：https://www.chromium.org/getting-involved/download-chromium/

或者通过 agent-browser 安装：

npx agent-browser install

许可证

MIT 许可证——详情请参阅 LICENSE 文件。