# web-search-mcp

**Repository Path**: openminds/web-search-mcp

## Basic Information

- **Project Name**: web-search-mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-21
- **Last Updated**: 2026-06-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Web Search MCP

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Code Style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.0-orange)](https://github.com/jlowin/fastmcp)

一个全面的、生产就绪的研究服务器，用于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)。为您的 LLM 客户端提供对网络的实时访问及更多功能。

## ✨ 功能特性

- **🌐 深度网络搜索**：通过 DuckDuckGo 进行文本和新闻搜索。
- **📄 内容提取**：使用 `trafilatura` 从任意 URL 提取无干扰的完整全文。支持多种输出格式（文本、Markdown、JSON）、元数据提取和内容过滤。
- **🛡️ 机器人检测绕过**：当网站阻止请求时（如 Cloudflare），自动回退到 Chrome TLS 模拟。
- **💻 技术文档**：针对开发者文档的定向搜索（Python、React 等）。

## 🚀 快速开始

### 安装

使用 `uv` 直接安装：

```bash
uv tool install git+https://github.com/sydasif/web-search-mcp.git
```

### 配置

将服务器添加到您的 MCP 客户端配置中（例如 `claude_desktop_config.json`）。您可以通过环境变量可选地配置速率限制，以避免被 DuckDuckGo 封禁。

```json
{
  "mcpServers": {
    "web-search": {
      "command": "web-search-mcp",
      "env": {
        "SEARCH_MCP_RATE_LIMIT_SEARCH": "30",
        "SEARCH_MCP_RATE_LIMIT_FETCH": "20"
      }
    }
  }
}
```

**可用环境变量：**

- `SEARCH_MCP_RATE_LIMIT_SEARCH`：每分钟最大搜索请求数（默认：`30`）。
- `SEARCH_MCP_RATE_LIMIT_FETCH`：每分钟最大页面获取请求数（默认：`20`）。

### 获取后端选项

`fetch_page` 工具支持三种后端模式来处理具有机器人检测的网站：

| 后端              | 描述                                                                   | 使用场景                                    |
| ---------------- | ---------------------------------------------------------------------- | ------------------------------------------- |
| `auto`（默认）    | 首先尝试 `httpx`，在遇到 403 或 Cloudflare 验证时回退到 `curl`          | 推荐用于大多数场景                          |
| `httpx`          | 轻量级异步 HTTP 客户端                                                  | 快速，但可能被某些网站阻止                  |
| `curl`           | 使用 `curl_cffi` 配合 Chrome 131 TLS 模拟                               | 绕过 Cloudflare 及类似的机器人过滤器        |

## 🛠️ 工具参考

| 工具            | 描述                                           | 关键参数                                                                                                                                                                                                                               |
| --------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `web_search`    | 通用搜索（网页、新闻）                          | `query`、`search_type`（"text"、"news"）、`max_results`、`time_range`、`region`、`page`、`response_format`（"json"、"markdown"）                                                                                                         |
| `fetch_page`    | 从 URL 提取干净的文章文本                        | `url`、`output_format`（"csv"、"html"、"json"、"markdown"、"python"、"txt"、"xml"、"xmltei"）、`include_metadata`、`include_tables`、`include_comments`、`include_images`、`max_length`、`timeout`、`backend`（"httpx"、"curl"、"auto"） |
| `search_docs`   | 搜索特定技术文档或域名                          | `query`、`domain`（例如 "docs.python.org"、"github.com"）                                                                                                                                                                              |

## 💻 开发

<details>
<summary>点击展开开发说明</summary>

1. **克隆仓库**

   ```bash
   git clone https://github.com/sydasif/web-search-mcp.git
   cd web-search-mcp
   ```

2. **同步依赖**

   ```bash
   uv sync
   ```

3. **运行测试**

   ```bash
   # 运行所有测试
   uv run pytest

   # 带覆盖率运行测试
   uv run pytest --cov=web_search_mcp
   ```

4. **代码检查与格式化**
   ```bash
   uv run ruff check .
   ```

</details>

## 📄 许可证

本项目基于 [MIT 许可证](https://opensource.org/licenses/MIT) 授权。