WebSearch-MCP
一个模型上下文协议 (MCP) 服务器实现，通过标准输入输出 (stdio) 传输提供网页搜索功能。该服务器集成了 WebSearch Crawler API 来检索搜索结果。
目录
Related MCP server: MCP Web Search Tool
关于
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
或者无需安装即可使用：
配置
可以使用环境变量来配置 WebSearch MCP 服务器：
例子：
# 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 轻松设置爬虫服务。
先决条件
启动爬虫服务
创建一个名为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:
启动服务：
验证服务是否正在运行：
测试爬虫 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 服务器，您可以使用附带的测试客户端：
这将启动 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 服务器问题
发展
从事此项目：
克隆存储库
安装依赖项： npm install
构建项目： npm run build
以开发模式运行： 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：
确保您拥有 npm 帐户并已登录（ npm login ）
更新 package.json 中的版本（ npm version patch|minor|major ）
运行npm publish
.npmignore文件确保发布的包中只包含必要的文件：
dist/中的编译代码
README.md 和 LICENSE 文件
包.json
贡献
欢迎贡献代码！欢迎提交 Pull 请求。
执照
国际学习中心
