WebSearch-MCP

WebSearch-MCP

一个通过 stdio 传输提供网页搜索功能的 Model Context Protocol（MCP）服务实现。此服务集成了 WebSearch Crawler API，用于获取搜索结果。

目录

• 关于
• 安装
• 配置
• 设置与集成
  • 设置爬虫服务
    • 前置条件
    • 启动爬虫服务
    • 测试爬虫 API
    • 自定义配置
  • 与 MCP 客户端集成
    • 快速参考：MCP 配置
    • Claude Desktop
    • Cursor IDE
    • Cline
• 使用方法
  • 参数
  • 搜索响应示例
  • 本地测试
  • 作为库使用
• 故障排除
  • 爬虫服务问题
  • MCP 服务问题
• 开发
  • 项目结构
  • 发布到 npm
• 贡献
• 许可证

关于

WebSearch-MCP 是一个 Model Context Protocol 服务，可为支持 MCP 的 AI 助手提供网页搜索功能。它支持 Claude 等 AI 模型实时搜索网页，获取有关任何主题的最新信息。

此服务集成了一个负责实际网页搜索的 Crawler API 服务，并使用标准化的 Model Context Protocol 与 AI 助手通信。

安装

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 WebSearch：

npx -y @smithery/cli install @mnhlt/WebSearch-MCP --client claude

手动安装

npm install -g websearch-mcp

也可以直接使用，无需安装：

npx websearch-mcp

配置

WebSearch MCP 服务可以使用环境变量进行配置：

• API_URL：WebSearch Crawler API 的 URL（默认值：http://localhost:3001）
• MAX_SEARCH_RESULT：请求中未指定时返回的最大搜索结果数（默认值：5）

示例：

# Configure API URL
API_URL=https://crawler.example.com npx websearch-mcp

# Configure maximum search results
MAX_SEARCH_RESULT=10 npx websearch-mcp

# Configure both
API_URL=https://crawler.example.com MAX_SEARCH_RESULT=10 npx websearch-mcp

设置与集成

设置 WebSearch-MCP 包括两个主要部分：配置负责实际网页搜索的爬虫服务，以及将 MCP 服务集成到 AI 客户端应用程序中。

设置爬虫服务

WebSearch MCP 服务需要爬虫服务来执行实际的网页搜索。你可以使用 Docker Compose 轻松设置爬虫服务。

前置条件

• Docker 和 Docker Compose

启动爬虫服务

1. 创建名为 docker-compose.yml 的文件，并写入以下内容：

version: '3.8'

services:
  crawler:
    image: laituanmanh/websearch-crawler:latest
    container_name: websearch-api
    restart: unless-stopped
    ports:
      - "3001:3001"
    environment:
      - NODE_ENV=production
      - PORT=3001
      - LOG_LEVEL=info
      - FLARESOLVERR_URL=http://flaresolverr:8191/v1
    depends_on:
      - flaresolverr
    volumes:
      - crawler_storage:/app/storage

  flaresolverr:
    image: 21hsmw/flaresolverr:nodriver
    container_name: flaresolverr
    restart: unless-stopped
    environment:
      - LOG_LEVEL=info
      - TZ=UTC

volumes:
  crawler_storage:

适用于 Mac Apple Silicon 的解决方法

version: '3.8'

services:
  crawler:
    image: laituanmanh/websearch-crawler:latest
    container_name: websearch-api
    platform: "linux/amd64"
    restart: unless-stopped
    ports:
      - "3001:3001"
    environment:
      - NODE_ENV=production
      - PORT=3001
      - LOG_LEVEL=info
      - FLARESOLVERR_URL=http://flaresolverr:8191/v1
    depends_on:
      - flaresolverr
    volumes:
      - crawler_storage:/app/storage

  flaresolverr:
    image: 21hsmw/flaresolverr:nodriver
    platform: "linux/arm64"
    container_name: flaresolverr
    restart: unless-stopped
    environment:
      - LOG_LEVEL=info
      - TZ=UTC

volumes:
  crawler_storage:

2. 启动服务：

docker-compose up -d

3. 验证服务是否正在运行：

docker-compose ps

4. 测试爬虫 API 健康检查端点：

curl http://localhost:3001/health

预期响应：

{
  "status": "ok",
  "details": {
    "status": "ok",
    "flaresolverr": true,
    "google": true,
    "message": null
  }
}

爬虫 API 将在 http://localhost:3001 上提供服务。

测试爬虫 API

你可以使用 curl 直接测试爬虫 API：

curl -X POST http://localhost:3001/crawl \
  -H "Content-Type: application/json" \
  -d '{
    "query": "typescript best practices",
    "numResults": 2,
    "language": "en",
    "filters": {
      "excludeDomains": ["youtube.com"],
      "resultType": "all" 
    }
  }'

自定义配置

你可以通过修改 docker-compose.yml 文件中的环境变量来自定义爬虫服务：

• PORT：爬虫 API 监听的端口（默认值：3001）
• LOG_LEVEL：日志级别（选项：debug、info、warn、error）
• FLARESOLVERR_URL：FlareSolverr 服务的 URL（用于绕过 Cloudflare 保护）

与 MCP 客户端集成

快速参考：MCP 配置

以下是不同客户端的 MCP 配置快速参考：

{
    "mcpServers": {
        "websearch": {
            "command": "npx",
            "args": [
                "websearch-mcp"
            ],
            "environment": {
                "API_URL": "http://localhost:3001",
                "MAX_SEARCH_RESULT": "5" // reduce to save your tokens, increase for wider information gain
            }
        }
    }
}

Windows 解决方法，因此问题

{
	"mcpServers": {
	  "websearch": {
            "command": "cmd",
            "args": [
				"/c",
				"npx",
                "websearch-mcp"
            ],
            "environment": {
                "API_URL": "http://localhost:3001",
                "MAX_SEARCH_RESULT": "1"
            }
        }
	}
  }

用法

此软件包使用 stdio 传输实现了一个 MCP 服务，并提供了一个 web_search 工具，包含以下参数：

参数

• query（必填）：要查找的搜索查询
• numResults（可选）：要返回的结果数量（默认值：5）
• language（可选）：搜索结果的语言代码（例如，'en'）
• region（可选）：搜索结果的地区代码（例如，'us'）
• excludeDomains（可选）：要从结果中排除的域名
• includeDomains（可选）：仅包含这些域名
• excludeTerms（可选）：要排除的词语
• resultType（可选）：要返回的结果类型（'all'、'news' 或 'blogs'）

搜索响应示例

以下是搜索响应示例：

{
  "query": "machine learning trends",
  "results": [
    {
      "title": "Top Machine Learning Trends in 2025",
      "snippet": "The key machine learning trends for 2025 include multimodal AI, generative models, and quantum machine learning applications in enterprise...",
      "url": "https://example.com/machine-learning-trends-2025",
      "siteName": "AI Research Today",
      "byline": "Dr. Jane Smith"
    },
    {
      "title": "The Evolution of Machine Learning: 2020-2025",
      "snippet": "Over the past five years, machine learning has evolved from primarily supervised learning approaches to more sophisticated self-supervised and reinforcement learning paradigms...",
      "url": "https://example.com/ml-evolution",
      "siteName": "Tech Insights",
      "byline": "John Doe"
    }
  ]
}

本地测试

要在本地测试 WebSearch MCP 服务，可以使用随附的测试客户端：

npm run test-client

这将启动 MCP 服务和一个简单的命令行界面，你可以在其中输入搜索查询并查看结果。

你还可以为测试客户端配置 API_URL：

API_URL=https://crawler.example.com npm run test-client

作为库使用

你可以通过编程方式使用此软件包：

import { createMCPClient } from '@modelcontextprotocol/sdk';

// Create an MCP client
const client = createMCPClient({
  transport: { type: 'subprocess', command: 'npx websearch-mcp' }
});

// Execute a web search
const response = await client.request({
  method: 'call_tool',
  params: {
    name: 'web_search',
    arguments: {
      query: 'your search query',
      numResults: 5,
      language: 'en'
    }
  }
});

console.log(response.result);

故障排除

爬虫服务问题

• API 无法访问：确保爬虫服务正在运行，并且可通过配置的 API_URL 访问。
• 没有可用的搜索结果：查看爬虫服务的日志，检查是否有错误：

  docker-compose logs crawler
  

• FlareSolverr 问题：某些网站使用 Cloudflare 保护。如果你看到相关错误，请检查 FlareSolverr 是否正常运行：

  docker-compose logs flaresolverr
  

MCP 服务问题

• 导入错误：确保使用的是最新版 MCP SDK：

  npm install -g @modelcontextprotocol/sdk@latest
  

• 连接问题：确保已为客户端正确配置 stdio 传输。

开发

要参与此项目的开发：

1. 克隆代码库
2. 安装依赖：npm install
3. 构建项目：npm run build
4. 以开发模式运行：npm run dev

该服务需要 WebSearch Crawler API，其定义见随附的 swagger.json 文件。确保 API 在配置的 API_URL 上运行。

项目结构

• .gitignore：指定 Git 应忽略的文件（node_modules、dist、logs 等）
• .npmignore：指定发布到 npm 时不应包含的文件
• package.json：项目元数据和依赖项
• src/：TypeScript 源文件
• dist/：编译后的 JavaScript 文件（构建时生成）

发布到 npm

要将此软件包发布到 npm：

1. 确保你拥有 npm 账户并已登录（npm login）
2. 更新 package.json 中的版本（npm version patch|minor|major）
3. 运行 npm publish

.npmignore 文件可确保发布的软件包仅包含必要文件：

• dist/ 中的编译代码
• README.md 和 LICENSE 文件
• package.json

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

ISC