Search MCP (Machine Learning Nerd)

Web MCP服务器

一个以隐私为重点的网络搜索MCP（模型上下文协议）服务器，提供网络搜索和内容提取功能。用途 SearxNG 作为主要的搜索引擎 谷歌抓取 作为一种退路。

特性

• 网页搜索 -使用类别过滤器（一般、新闻、图像、视频、科学、文件）搜索网络
• 内容提取 -从URL中提取可读内容作为标记
• 搜索建议 -获取查询建议以进行更好的搜索
• 注重隐私 -使用SearxNG元搜索引擎
• 后备支援 -如果SearxNG不可用，则自动回退到谷歌抓取
• 相关性排名 -支持查询的重新排序、重复数据删除和低信号过滤
• 安全意识搜索 -CVE/安全查询优先考虑可信的咨询来源
• 速率限制 -内置速率限制，防止滥用
• Docker就绪 -包括SearxNG的单集装箱部署

提供的工具

安装

选项1:Docker（推荐）

# Build the image
docker build -t web-mcp:latest .

# Run the container
docker run --rm -i web-mcp:latest

选项2:Python包

# Clone the repository
git clone https://github.com/your-org/web-mcp.git
cd web-mcp

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt  # Optional: tests, lint, type checks

# Or install as package
pip install -e .

# Run the server
python -m web_mcp.server

选项3：使用外部SearxNG

如果您有一个现有的SearxNG实例：

# Set the SearxNG URL
export SEARXNG_URL=http://your-searxng-instance:8080

# Run the MCP server
python -m web_mcp.server

配置

环境变量

配置文件

创建一个 .env 项目根目录中的文件：

SEARXNG_URL=http://localhost:8080
SEARXNG_TIMEOUT=10
SEARCH_ENGINE_PROFILE_MODE=auto
SEARCH_SECURITY_ENGINES=brave,bing,duckduckgo,wikipedia,github,stackoverflow
SEARCH_GENERAL_ENGINES=
SEARCH_CANDIDATE_MULTIPLIER=5
SEARCH_MAX_CANDIDATES=30
SEARCH_MIN_QUALITY_SCORE=2.5
FALLBACK_ENABLED=true
RATE_LIMIT_REQUESTS=30
RATE_LIMIT_PERIOD=60
MAX_CONTENT_LENGTH=10000
FETCH_ALLOW_PRIVATE_NETWORK=false
DEFAULT_SEARCH_LIMIT=5
LOG_LEVEL=INFO
JSON_LOGS=false

与MCP客户端一起使用

克劳德桌面版

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "web-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "web-mcp:latest"]
    }
  }
}

或者用Python：

{
  "mcpServers": {
    "web-mcp": {
      "command": "python",
      "args": ["-m", "web_mcp.server"],
      "env": {
        "SEARXNG_URL": "http://localhost:8080"
      }
    }
  }
}

其他MCP客户端

服务器使用stdio传输，使其与任何兼容MCP的客户端兼容。

工具参考

网络搜索

在网上搜索信息。

参数：

例子：

{
  "name": "web_search",
  "arguments": {
    "query": "Python async programming",
    "category": "general",
    "limit": 5
  }
}

答复：

# Search Results for: Python async programming

*Provider: searxng | 5 results*

---

## 1. Async IO in Python: A Complete Guide
**URL:** https://realpython.com/async-io-python/

Complete guide to async programming in Python...

## 2. Python asyncio Documentation
**URL:** https://docs.python.org/3/library/asyncio.html

Official Python asyncio documentation...

食品成分

从URL中提取可读内容。 默认情况下，仅公开 http/https 允许目标(FETCH_ALLOW_PRIVATE_NETWORK=false).

参数：

例子：

{
  "name": "fetch_content",
  "arguments": {
    "url": "https://example.com/article",
    "max_length": 5000
  }
}

答复：

# Article Title

> Brief description of the article

**Author:** John Doe
**Source:** example.com
**URL:** https://example.com/article

---

[Article content in markdown format...]

get_建议

获取搜索查询建议。

参数：

例子：

{
  "name": "get_suggestions",
  "arguments": {
    "query": "python asyn"
  }
}

答复：

# Suggestions for: python asyn

1. python async await
2. python asyncio tutorial
3. python async http requests
4. python async context manager
5. python asyncio vs threading

发展

设置

# Create virtual environment
python -m venv venv
source venv/bin/activate

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

# Run tests
pytest

# Run linting
ruff check src tests

# Run type checking
mypy src

手动MCP烟雾测试（容器+stdio）

使用此选项验证CLI代理使用的真实MCP集成路径。

test.py 使用以下命令将容器化MCP服务器作为子进程启动： docker run --rm -i web-mcp:latest 并验证 initialize, list_tools，以及 call_tool 流动。

容器合约仅支持stdio。分离模式(docker run -d ...)故意不支持MCP客户端。

# 1) Build image
docker build -t web-mcp:latest .

# 2) Run smoke script from repo root (with your virtualenv active)
.venv/bin/python test.py

# Optional: custom inputs
.venv/bin/python test.py \
  --image web-mcp:latest \
  --query "python asyncio" \
  --suggest-query "python asyn" \
  --content-url "https://example.com" \
  --limit 3 \
  --max-length 800

# Optional: full response blocks
.venv/bin/python test.py --verbose

什么 test.py 验证：

• 针对容器化服务器的MCP会话初始化
• 预期工具已注册： web_search, fetch_content, get_suggestions
• 工具调用通过MCP stdio传输成功

脚本行为注释：

• 如果你只通过其中一个 --query 或 --suggest-query，该值可用于两者
• test.py 默认情况下打印紧凑的通过/失败摘要；使用 --verbose 显示完整的工具输出
• 使用 --docker-command 如果您的环境使用不同的容器运行时命令

项目结构

web-mcp/
├── src/web_mcp/
│   ├── __init__.py
│   ├── config.py           # Configuration management
│   ├── server.py           # MCP server entry point
│   ├── search/
│   │   ├── base.py         # SearchResult, SearchResponse, SearchProvider ABC
│   │   ├── searxng.py      # SearxNG provider
│   │   ├── google.py       # Google scraping fallback
│   │   ├── fallback.py     # Fallback orchestration + quality gate
│   │   ├── relevance.py    # Scoring, ranking, dedup, snippet cleaning
│   │   └── provider_registry.py # Shared provider singleton
│   ├── tools/
│   │   ├── web_search.py   # web_search tool
│   │   ├── fetch_content.py # fetch_content tool
│   │   └── suggestions.py  # get_suggestions tool
│   └── utils/
│       ├── logger.py       # Structured logging
│       ├── rate_limiter.py  # Rate limiting
│       ├── content_extractor.py # HTML-to-markdown extraction
│       └── validation.py   # Shared input validation
├── tests/                  # Test suite
├── docker/                 # Docker configuration
│   ├── searxng/           # SearxNG settings
│   └── entrypoint.sh      # Container entrypoint
├── Dockerfile             # Single-container Docker build
├── pyproject.toml         # Python project config
├── requirements.txt       # Runtime dependencies
└── requirements-dev.txt   # Test/lint/type dependencies

故障排除

常见问题

1.SearxNG连接被拒绝

Error: Failed to connect to SearxNG

• 确保SearxNG正在运行： curl http://localhost:8080/config
• 检查 SEARXNG_URL 环境变量
• 如果通过MCP stdio使用Docker，请确保映像是最新的(docker build -t web-mcp:latest .)

2.谷歌费率限制

Error: Google rate limit hit (429)

• 降低请求频率
• SearxNG应作为主要使用；谷歌只是退路
• 请等待几分钟，然后重试

3.内容提取失败

Error: Failed to extract content from page

• 页面可能使用JavaScript渲染（不支持）
• 该页面可能会阻止自动请求
• 尝试使用其他URL

4.导入错误

ModuleNotFoundError: No module named 'web_mcp'

• 确保您处于虚拟环境中
• 安装软件包： pip install -e .
• 检查 PYTHONPATH 包括 src/

调试模式

启用调试日志记录：

export LOG_LEVEL=DEBUG
python -m web_mcp.server

Docker调试

# Run container interactively
docker run -it --entrypoint /bin/sh web-mcp:latest

# View logs
docker logs 

安全注意事项

• SearxNG秘密：更改 SEARXNG_SECRET 生产中
• 速率限制：配置 RATE_LIMIT_REQUESTS 防止滥用
• 网络：容器暴露端口8080（仅用于调试）
• 用户权限：容器默认为根管理进程；强化用户/生产权限

许可证

MIT许可证-请参阅 许可证 了解详情。

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 运行测试： pytest
5. 提交拉取请求

致谢

• SearxNG -尊重隐私的元搜索引擎
• 主控程序 -模型上下文协议
• 编织 -Web内容提取