Web Search Fast

网络搜索MCP

通过以下方式为LLM客户提供高性能网络搜索服务 模型上下文协议由迷彩隐形浏览器提供支持。

英语 | 中文

______________________________________________________________________

______________________________________________________________________

特性

• 3搜索引擎 --谷歌、必应、DuckDuckGo自动回退
• 多深度刮削 --SERP解析→ 全文提取→ 出站链接爬行
• 隐形浏览器 — 迷彩 反检测Firefox（GeoIP、人性化、区域设置）
• 自动缩放池 --浏览器池以80%的利用率自动扩展，可配置上限
• 管理员仪表板 -搜索分析、系统监控、API密钥管理、IP禁止
• API密钥认证 --内置密钥生成(wsm_ 前缀），带有呼叫限制和撤销
• 双输出 --JSON和Markdown格式
• REST API -标准HTTP API和MCP协议

快速开始

Docker（推荐）

git clone https://github.com/nicepkg/web-search-mcp.git
cd web-search-mcp

# Configure
cp .env.example .env
# Edit .env — set ADMIN_TOKEN

# Launch
docker compose up -d

# Verify
curl http://127.0.0.1:8897/health

创建API密钥并注册到Claude代码

# 1. Create an API key via Admin API
curl -X POST http://127.0.0.1:8897/admin/api/keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "claude-code", "call_limit": 10000}'
# Save the returned wsm_xxx key (only shown once)

# 2. Register MCP to Claude Code
claude mcp add-json -s user web-search-fast '{
  "type": "http",
  "url": "http://127.0.0.1:8897/mcp",
  "headers": {"Authorization": "Bearer wsm_your-api-key-here"}
}'

# 3. Restart Claude Code session

或使用管理员仪表板 http://127.0.0.1:8897/admin 以视觉方式创建密钥。

MCP工具

web_search参数

搜索深度

认证模型

• ADMIN_TOKEN 具有对所有端点的超级用户访问权限
• wsm_ 密钥只能访问MCP和搜索端点（不能访问管理员API）
• 如果不 ADMIN_TOKEN 已设置且不存在API键，所有终结点都处于打开状态

REST API

可与MCP一起提供标准HTTP API。

# GET
curl 'http://127.0.0.1:8897/search?q=python+asyncio&engine=duckduckgo&max_results=5' \
  -H 'Authorization: Bearer wsm_your-key'

# POST
curl -X POST http://127.0.0.1:8897/search \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer wsm_your-key' \
  -d '{"query": "python asyncio", "engine": "duckduckgo", "depth": 2, "max_results": 5}'

管理员仪表板

访问 http://127.0.0.1:8897/admin 并使用登录 ADMIN_TOKEN.

• 仪表盘 --搜索统计数据、CPU/内存监控、浏览器池状态、延迟图表、引擎分布、成功率
• API密钥 --创建/撤销具有呼叫限制的密钥
• IP禁令 --禁止/取消禁止IP地址
• 搜索日志 --使用IP过滤的搜索历史记录

引擎状态

当谷歌被屏蔽时，会自动回退：DuckDuckGo→ Bing.

部署

端点

反向代理（Nginx）

如果使用HTTPS在Nginx后面部署：

location / {
    proxy_pass http://127.0.0.1:8897;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Authorization $http_authorization;

    # Required for MCP Streamable HTTP (SSE)
    proxy_buffering off;
    proxy_cache off;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_read_timeout 120s;
    proxy_send_timeout 120s;
}

Cloudflare用户：为添加WAF异常规则 /mcp 路径，或使用仅DNS模式（灰色云）。

环境变量

发展

# Install dependencies
pip install -e ".[dev]"

# Install Camoufox browser
python -m camoufox fetch

# Start server
python -m src.mcp_server --transport http --host 127.0.0.1 --port 8897

# Run tests (96 tests)
pytest tests/ -v

# Type check
mypy src/

# Lint & format
ruff check src/ --fix && ruff format src/

建筑

web-search-mcp/
├── src/
│   ├── mcp_server.py           # MCP server entry (FastMCP + middleware + Admin)
│   ├── config.py               # Configuration management
│   ├── api/
│   │   ├── routes.py           # HTTP API routes
│   │   └── schemas.py          # Pydantic request/response models
│   ├── core/
│   │   └── search.py           # Search logic (shared by MCP + HTTP)
│   ├── engine/
│   │   ├── base.py             # Search engine abstract base class
│   │   ├── google.py           # Google (JS DOM + captcha detection)
│   │   ├── bing.py             # Bing (global.bing.com)
│   │   └── duckduckgo.py       # DuckDuckGo (HTML-lite)
│   ├── scraper/
│   │   ├── browser.py          # BrowserPool (auto-scaling + health monitoring)
│   │   ├── parser.py           # HTML content parser
│   │   └── depth.py            # Multi-depth scraping
│   ├── formatter/
│   │   ├── json_fmt.py         # JSON formatter
│   │   └── markdown_fmt.py     # Markdown formatter
│   ├── admin/
│   │   ├── database.py         # SQLite init + migrations
│   │   ├── repository.py       # Data access layer
│   │   ├── routes.py           # Admin REST API
│   │   └── static/             # Admin SPA build output
│   └── middleware/
│       ├── api_key_auth.py     # Bearer token auth (ADMIN_TOKEN + DB keys)
│       ├── ip_ban.py           # IP ban middleware
│       └── search_log.py       # Search logging middleware
├── admin-ui/                   # Admin frontend (React + Vite + Tailwind)
├── tests/                      # Test suite (96 tests)
├── docker-compose.yml
├── Dockerfile
└── pyproject.toml

技术栈

______________________________________________________________________

功能特性

• 三大搜索引擎 — Google、Bing、DuckDuckGo，自动回退
• 多层深度抓取 — SERP 解析 → 正文提取 → 外链抓取
• 反检测浏览器 — Camoufox 真实浏览器指纹（GeoIP、Humanize、Locale）
• 自动扩容 — 浏览器池并发达 80% 时自动扩容，上限可配
• Admin 管理面板 — 搜索统计、系统监控、API Key 管理、IP 封禁
• API Key 认证 — 内置密钥生成（wsm_ 前缀），支持调用限额和吊销
• 双格式输出 --JSON/Markdown
• REST API — 标准 HTTP API，与 MCP 协议并行提供

快速开始

Docker 部署（推荐）

git clone https://github.com/nicepkg/web-search-mcp.git
cd web-search-mcp

# 配置环境变量
cp .env.example .env
# 编辑 .env，设置 ADMIN_TOKEN

# 启动服务
docker compose up -d

# 验证
curl http://127.0.0.1:8897/health

创建 API Key 并注册到 Claude Code

# 1. 通过 Admin API 创建 API Key
curl -X POST http://127.0.0.1:8897/admin/api/keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "claude-code", "call_limit": 10000}'
# 保存返回的 wsm_xxx 密钥（仅创建时可见）

# 2. 注册 MCP 到 Claude Code
claude mcp add-json -s user web-search-fast '{
  "type": "http",
  "url": "http://127.0.0.1:8897/mcp",
  "headers": {"Authorization": "Bearer wsm_your-api-key-here"}
}'

# 3. 重启 Claude Code 会话

也可以访问 http://127.0.0.1:8897/admin 通过 Admin 面板可视化创建密钥。

本地 stdio 模式

无需 Docker，Claude Code 直接通过 stdin/stdout 通信：

pip install -e .
python -m camoufox fetch

claude mcp add-json -s user web-search-fast '{
  "type": "stdio",
  "command": "python",
  "args": ["-m", "src.mcp_server", "--transport", "stdio"],
  "env": {"PYTHONUNBUFFERED": "1"},
  "cwd": "'$(pwd)'"
}'

认证模型

• ADMIN_TOKEN 拥有所有端点的超级权限
• wsm_ 密钥只能访问 MCP 和搜索端点（不能访问 Admin API）
• 如果未配置 ADMIN_TOKEN 且无 API Key，所有端点开放访问

反向代理注意事项

使用 Nginx 反向代理时，MCP Streamable HTTP 需要关闭缓冲：

proxy_buffering off;
proxy_http_version 1.1;
proxy_set_header Connection '';
proxy_read_timeout 120s;

Claude Code 如何默认使用这个工具进行搜索

编辑 ~/.claude/CLAUDE.md 添加下面的内容

## Web Search

* 优先使用 `web-search-fast`

Cloudflare 用户：需要为 /mcp 路径添加 WAF 例外规则，或使用 DNS-only 模式（灰色云朵）。

许可证

麻省理工学院