Skip to main content
Glama
enesjakozh
mnhlt

WebSearch-MCP

by mnhlt
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

WebSearch-MCP

铁匠徽章

一个模型上下文协议 (MCP) 服务器实现，通过标准输入输出 (stdio) 传输提供网页搜索功能。该服务器集成了 WebSearch Crawler API 来检索搜索结果。

目录

Related MCP server: MCP Server for Google Search

关于

WebSearch-MCP 是一个模型上下文协议 (MCP) 服务器，为支持 MCP 的 AI 助手提供网页搜索功能。它允许像 Claude 这样的 AI 模型实时搜索网页，检索任何主题的最新信息。

该服务器集成了处理实际网络搜索的爬虫 API 服务，并使用标准化模型上下文协议与 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 服务器需要爬虫服务来执行实际的 Web 搜索。您可以使用 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 ：日志级别（选项：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 （可选）：返回的结果类型（“全部”、“新闻”或“博客”）

搜索响应示例

以下是搜索响应的示例：

{
  "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文件确保发布的包中只包含必要的文件：

  • dist/中的编译代码

  • README.md 和 LICENSE 文件

  • 包.json

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

执照

国际学习中心

Available Tools

1 tool

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.0.0
    • First observedweb_search
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 1 tool

Disambiguation5/5

Only one tool exists, so there is no ambiguity. The single tool's purpose is clearly defined as searching the web.

Naming Consistency5/5

With only one tool, naming consistency is trivially maintained. The name 'web_search' follows a clear verb_noun pattern.

Tool Count3/5

A single tool for a web search server is minimal but acceptable for basic functionality. However, a more complete server might include tools for fetching page content or image search, making the count borderline.

Completeness3/5

The server provides only a search tool, missing common complementary tools like fetching web page content or performing advanced searches. This leaves notable gaps for typical workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches