AI导哈

网页搜索协议服务

WebSearch-MCP是一个通过标准输入输出传输提供网页搜索能力的模型上下文协议服务器实现，集成网页搜索爬虫API获取搜索结果。

  • by mnhlt
  • JavaScript
  • 本地部署
  • 42 星标
  • 更新于
在 GitHub 查看 mnhlt/WebSearch-MCP

使用说明

WebSearch MCP

一种模型上下文协议（MCP）服务器实现，通过stdio传输提供web搜索功能。此服务器与WebSearch Crawler API集成以检索搜索结果。

目录

关于

WebSearch MCP是一个模型上下文协议服务器，为支持MCP的AI助手提供网络搜索功能。它允许像克劳德这样的人工智能模型实时搜索网络，检索有关任何主题的最新信息。

该服务器与处理实际网络搜索的Crawler API服务集成，并使用标准化的模型上下文协议与人工智能助手通信。

安装

通过Smithery安装

通过以下方式自动安装克劳德桌面的WebSearch 史密瑟里:

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

手动安装

npm install -g websearch-mcp

或者在不安装的情况下使用：

npx websearch-mcp

配置

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

  • API_URL：Web搜索爬网程序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轻松设置爬虫服务。

先决条件

启动爬网程序服务

  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:
  1. 启动服务：
docker-compose up -d
  1. 验证服务是否正在运行：
docker-compose ps
  1. 测试爬网程序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：日志记录级别（选项：调试、信息、警告、错误）
  • 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 （可选）：搜索结果的地区代码（例如“我们”）
  • excludeDomains （可选）：要从结果中排除的域
  • includeDomains （可选）：仅在结果中包含这些域
  • excludeTerms （可选）：从结果中排除的条款
  • resultType （可选）：要返回的结果类型（“全部”、“新闻”或“博客”）

搜索响应示例

以下是一个搜索响应的示例：

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

服务器需要包含的swagger.json文件中定义的WebSearch Crawler API。确保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 file确保发布的包中只包含必要的文件：

  • 编译后的代码 dist/
  • README.md和许可证文件
  • package.json

贡献

欢迎投稿！请随时提交拉取请求。

许可证

国际协调委员会

相关 MCP