网页搜索-MCP

Name: 网页搜索-MCP
Author: mnhlt

作者：mnhlt19 星标更新：2025-05-01

安装使用来源：spider==github.com

项目介绍

WebSearch-MCP

这是一个实现了Model Context Protocol (MCP)服务器，提供通过stdio传输的网络搜索能力。该服务器与一个WebSearch爬虫API集成，以检索搜索结果。

关于

WebSearch-MCP是一个Model Context Protocol服务器，它为支持MCP的AI助手提供了网络搜索能力。它允许像Claude这样的AI模型实时搜索网络，获取任何主题的最新信息。

该服务器与一个处理实际网络搜索的爬虫API服务集成，并使用标准化的Model Context Protocol与AI助手通信。

安装

通过Smithery安装

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

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

手动安装

npm install -g websearch-mcp

或者不进行安装直接使用：

npx websearch-mcp

配置

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

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

示例：

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

# 配置最大搜索结果
MAX_SEARCH_RESULT=10 npx websearch-mcp

# 同时配置两者
API_URL=https://crawler.example.com MAX_SEARCH_RESULT=10 npx websearch-mcp

设置与集成

设置WebSearch-MCP涉及两个主要部分：配置执行实际网络搜索的爬虫服务，以及将MCP服务器与您的AI客户端应用程序集成。

设置爬虫服务

WebSearch MCP服务器需要一个爬虫服务来执行实际的网络搜索。您可以轻松地使用Docker Compose设置爬虫服务。

前提条件

Docker 和 Docker Compose

启动爬虫服务

创建一个名为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:

启动服务：

docker-compose up -d

验证服务是否正在运行：

docker-compose ps

测试爬虫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 最佳实践",
    "numResults": 2,
    "language": "zh",
    "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" // 减少以节省令牌，增加以获得更广泛的信息
            }
        }
    }
}

针对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（可选）：搜索结果的语言代码（例如，'zh'）
region（可选）：搜索结果的区域代码（例如，'cn'）
excludeDomains（可选）：从结果中排除的域名
includeDomains（可选）：仅包括这些域名在结果中
excludeTerms（可选）：从结果中排除的术语
resultType（可选）：要返回的结果类型（'all', 'news', 或 'blogs'）

示例搜索响应

这里是一个搜索响应的示例：

{
  "query": "机器学习趋势",
  "results": [
    {
      "title": "2025年顶级机器学习趋势",
      "snippet": "2025年的关键机器学习趋势包括多模态AI、生成模型和量子机器学习在企业中的应用...",
      "url": "https://example.com/machine-learning-trends-2025",
      "siteName": "AI研究今日",
      "byline": "Jane博士"
    },
    {
      "title": "机器学习的演变：2020-2025",
      "snippet": "在过去五年中，机器学习已经从主要的监督学习方法演变为更复杂的自我监督和强化学习范式...",
      "url": "https://example.com/ml-evolution",
      "siteName": "科技洞察",
      "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';

// 创建一个MCP客户端
const client = createMCPClient({
  transport: { type: 'subprocess', command: 'npx websearch-mcp' }
});

// 执行网络搜索
const response = await client.request({
  method: 'call_tool',
  params: {
    name: 'web_search',
    arguments: {
      query: '您的搜索查询',
      numResults: 5,
      language: 'zh'
    }
  }
});

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传输已正确配置以供您的客户端使用。

开发

要为此项目工作：

克隆仓库
安装依赖项：npm install
构建项目：npm run build
在开发模式下运行：npm run dev

服务器期望一个如包含的swagger.json文件中定义的WebSearch爬虫API。确保API正在配置的API_URL上运行。

项目结构

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

发布到npm

要将此包发布到npm：

确保您有npm帐户并已登录（npm login）
更新package.json中的版本（npm version patch|minor|major）
运行npm publish

.npmignore文件确保只包含发布的必要文件：

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

贡献

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

许可

ISC