WebSurfer MCP
Securely fetch and extract clean text from the web for LLMs.
MCP Server • src-layout Python package • SSRF Protection
WebSurfer是一个模型上下文协议（MCP）服务器，旨在为大型语言模型（LLM）提供安全高效的web内容访问。
核心功能
- 高级URL验证：使用
ipaddress模块，用于在发生任何获取之前阻止私有、环回、链接本地和保留目标。 - 优化内容提取：利用
trafilatura和BeautifulSoup4从HTML中提取高质量、可读的文本，有效地删除导航、标题和脚本等样板。 - 资源管理：强制执行严格的内容大小限制和请求超时，以确保系统稳定性和性能。
- 重定向安全：验证每个重定向跳转，并拒绝重定向到被阻止的方案、本地主机、私有IP文字或不安全的DNS目标。
- 速率限制：内置请求限制，以防止服务滥用和管理资源消耗。
- 稳健的错误处理：为网络问题、HTTP错误和内容解析失败提供精细反馈。
项目布局
websurfer-mcp/
├── src/websurfer_mcp/
│ ├── cli.py
│ ├── config.py
│ ├── extractor.py
│ ├── networking.py
│ ├── server.py
│ └── url_validation.py
├── tests/
├── docs/images/
├── pyproject.toml
└── run_tests.py关键运行时组件：
WebSurferServer：MCP运输和工具登记。TextExtractor：异步HTTP获取和可读文本提取。SafeResolver：拒绝私有和保留IP答案的DNS解析保护。URLValidator：URL规范化和SSRF重点验证。Config：环境驱动的运行时配置。
安装
先决条件
- Python 3.12或更高版本
- 紫外线 包管理器
设置
- 克隆存储库:
git clone https://github.com/crybo-rybo/websurfer-mcp
cd websurfer-mcp- 安装运行时依赖项:
uv sync- 安装开发工具:
uv sync --group dev用法
服务器执行
服务器通过标准I/O（stdio）进行通信，并与任何符合MCP的客户端兼容。
使用控制台脚本或包模块：
uv run websurfer-mcp serve
uv run python -m websurfer_mcp serve手动测试
您可以直接从命令行验证提取功能：
uv run websurfer-mcp test --url "https://example.com"桌面客户端集成
克劳德桌面版
要将WebSurfer MCP与Claude Desktop一起使用，请将以下配置添加到您的 claude_desktop_config.json 文件。
路径位置：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%\Claude\claude_desktop_config.json
配置：
替换 /path/to/websurfer-mcp 带有克隆存储库的绝对路径。
更新配置后，重新启动Claude Desktop以启用 search_url 工具。
{
"mcpServers": {
"websurfer": {
"command": "uv",
"args": [
"--directory",
"/path/to/websurfer-mcp",
"run",
"python",
"-m",
"websurfer_mcp",
"serve"
]
}
}
}配置
可以使用以下环境变量配置服务器：
| 变量 | 默认值 | 描述 |
|---|---|---|
MCP_DEFAULT_TIMEOUT | 10 | 默认请求超时时间（秒）。 |
MCP_MAX_TIMEOUT | 60 | 允许的最大超时时间（秒）。 |
MCP_MAX_REDIRECTS | 10 | 要遵循的最大重定向跳数。 |
MCP_USER_AGENT | websurfer-mcp/0.2.0 | 传出请求的用户代理字符串。 |
MCP_MAX_CONTENT_LENGTH | 10485760 | 最大内容大小（以字节为单位）（默认10MB）。 |
发展
运行测试套件：
uv run pytest运行质量检查：
uv run ruff check .
uv run ruff format .运行一个聚焦模块：
uv run python run_tests.py --module test_server安全
WebSurfer MCP的设计以安全性为首要考虑因素。它明确地阻止了：
- 私有IP范围（例如10.0.0.0/8、192.168.0.0/16）
- 环回地址（例如127.0.0.1，：：1）
- 链接本地和保留地址
- 非HTTP/HTTPS方案（例如，file://、ftp://、javascript:）
- 将跳转重定向到被阻止的目的地
- 将公共主机名解析为私有或保留IP的DNS应答
______________________________________________________________________
与开发 模型上下文协议.