AI导哈

网络搜索MCP服务器

一个轻量级、高性能的模型上下文协议（MCP）服务器，用于网络搜索和网页抓取，支持多搜索提供商自动回退功能。

  • by SamWongML
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 SamWongML/web-search-mcp

使用说明

网络搜索MCP

一个轻量级、高性能的模型上下文协议（MCP）服务器，用于网络搜索和抓取。设计为Firecrawl MCP的自托管替代方案，支持多个搜索提供商自动回退。

特性

  • 多个搜索提供商：SerpAPI，Tavily搜索，勇敢搜索，DuckDuckGo
  • 自动回退：失败时无缝退回下一个提供商
  • Web剪贴：从任何网页中提取干净的标记
  • 搜索+报废：可选择将抓取的内容附加到搜索结果中
  • 批量操作：同时删除多个URL
  • URL发现：查找网页上的所有链接
  • 速率限制：每个提供商的内置速率限制
  • 缓存：具有可配置TTL的LRU缓存
  • Docker就绪：生产就绪的集装箱化
  • 综合测试：单元、集成、E2E和Docker测试套件

安装

使用紫外线（推荐）

# Install dependencies
uv sync

# With dev dependencies
uv sync --group dev

使用Docker

cd docker
docker-compose up -d

配置

创建一个 .env 文件基于 .env.example:

cp .env.example .env

环境变量

变量 默认值 描述
WEBSEARCH_HOST 0.0.0.0 服务器主机
WEBSEARCH_PORT 8000 服务器端口
WEBSEARCH_LOG_LEVEL INFO 日志记录级别
WEBSEARCH_SERPAPI_KEY - SerpAPI密钥（可选）
WEBSEARCH_TAVILY_API_KEY - Tavilly搜索API密钥（可选）
WEBSEARCH_BRAVE_API_KEY - 勇敢搜索API密钥（可选）
WEBSEARCH_USE_BROWSER_SCRAPER true 更喜欢Crawl4AI，退回特拉弗拉图拉
WEBSEARCH_CACHE_TTL_SECONDS 3600 缓存生存时间
WEBSEARCH_CACHE_MAX_SIZE 1000 最大缓存条目数
WEBSEARCH_SEARCH_SCRAPE_MAX_CONCURRENT 5 最大并发抓取次数 web_search
WEBSEARCH_DEFAULT_SCRAPE_FORMATS markdown 默认抓取输出格式
WEBSEARCH_DEFAULT_ONLY_MAIN_CONTENT true 默认主内容过滤

用法

运行服务器

# With uv
uv run python -m web_search_mcp

# Or with uvicorn
uv run uvicorn web_search_mcp.app:app --host 0.0.0.0 --port 8000

# Or with Docker
docker-compose -f docker/docker-compose.yml up

MCP工具

服务器公开了五个MCP工具：

1.网络搜索

使用配置了自动回退功能的提供程序搜索web。可选择附加刮擦的内容。

{
  "query": "python async programming",
  "max_results": 10,
  "language": "en",
  "region": "us",
  "safe_search": true,
  "include_domains": ["docs.python.org"],
  "scrape_options": {
    "formats": ["markdown", "text"],
    "only_main_content": true,
    "max_length": 20000
  },
  "max_scrape_results": 5
}

2.scrape_url

删除单个URL并提取干净的markdown内容。

{
  "url": "https://example.com/article",
  "include_links": true,
  "include_images": false,
  "formats": ["markdown", "text"],
  "only_main_content": true,
  "include_tags": ["main"],
  "exclude_tags": [".ads"],
  "max_length": 20000
}

3.批次_裂纹

同时删除多个URL。

{
  "urls": [
    "https://example.com/page1",
    "https://example.com/page2"
  ],
  "max_concurrent": 5,
  "include_links": false,
  "formats": ["markdown"]
}

4.发现世界

发现网页上的所有链接。

{
  "url": "https://example.com",
  "max_urls": 100
}

5.地图_世界

使用可选过滤器映射网站上的URL。

{
  "url": "https://example.com",
  "max_urls": 200,
  "search": "docs",
  "same_domain_only": true,
  "include_subdomains": false,
  "exclude_patterns": ["\\?utm_"]
}

从克劳德代码连接

添加到您的Claude Code MCP配置中：

{
  "mcpServers": {
    "web-search": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

健康终点

端点 描述
GET / 服务器信息和可用工具
GET /health 详细的健康检查
GET /ready 准备就绪探头（K8s）
GET /alive 活体探头（K8s）

建筑

src/web_search_mcp/
├── config/          # Settings and configuration
├── models/          # Pydantic data models
├── providers/       # Search provider implementations
│   ├── serpapi.py
│   ├── tavily.py
│   ├── brave.py
│   └── duckduckgo.py
├── scrapers/        # Web scraper implementations
│   ├── trafilatura_scraper.py
│   ├── crawl4ai_scraper.py
│   └── jina_reader.py
├── tools/           # MCP tool definitions
├── utils/           # Utilities (cache, rate limiter)
├── app.py           # Starlette ASGI application
└── server.py        # FastMCP server setup

提供商优先级

按顺序尝试提供者，直到成功为止：

  1. 塔维利搜索 （要求 WEBSEARCH_TAVILY_API_KEY)
  2. 鸭鸭搜 （始终可用回退）
  3. SerpAPI （要求 WEBSEARCH_SERPAPI_KEY)
  4. 勇敢搜索 （要求 WEBSEARCH_BRAVE_API_KEY)

发展

设置

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies, including dev tools
uv sync --group dev

运行测试

# All tests
uv run pytest

# Unit tests only
uv run pytest tests/unit/

# Integration tests
uv run pytest tests/integration/

# E2E tests
uv run pytest tests/e2e/

# Docker tests (requires Docker)
uv run pytest tests/docker/ -m docker

# With coverage
uv run pytest --cov=web_search_mcp --cov-report=html

代码质量

# Format code
uv run ruff format .

# Lint
uv run ruff check .

# Type check (primary)
uv run pyright

# Install local pre-commit hooks
uv run pre-commit install
uv run pre-commit run --all-files

可复制的依赖工作流

# Verify lock file is current
uv lock --check

# Sync exactly from lock file
uv sync --frozen --group dev

码头工人

发展

cd docker
docker-compose -f docker-compose.yml up --build

生产

cd docker
docker-compose -f docker-compose.prod.yml up -d

建筑图片

# Development image
docker build -f docker/Dockerfile.dev -t web-search-mcp:dev .

# Production image
docker build -f docker/Dockerfile -t web-search-mcp:latest .

API限值

提供商 免费等级
SerpAPI 100/月
塔维利 1000/月
勇敢搜索 每月2000
DuckDuckGo 无限（非官方）

发布策略

  • 标签格式： vX.Y.Z （例如， v0.2.0)
  • CI发布工作流通过可信发布（OIDC）构建分发并发布到PyPI
  • 创建 pypi 启用生产发布前的GitHub环境

许可证

麻省理工学院

相关 MCP