# OvertliDS
## 基本信息
- Slug: `overtlids-mcp-searxng-enhanced`
- Source: modelscope
- Publisher: @OvertliDS/mcp-searxng-enhanced
- Categories: search / web-scraping / browser-automation
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@OvertliDS/mcp-searxng-enhanced
## 简介
暂无描述。
## MCP Server 详情

# MCP SearXNG 增强服务器

一个用于分类感知的网络搜索、网站抓取和日期/时间工具的模型上下文协议（MCP）服务器。专为与 SearXNG 和现代 MCP 客户端无缝集成而设计。

## 特性

- 🔍 支持分类的 SearXNG 网络搜索（通用、图片、视频、文件、地图、社交媒体）
- 📄 具有引用元数据的网站内容抓取及自动 Reddit URL 转换
- 💾 带有自动新鲜度验证的内存缓存
- 🚦 基于域名的速率限制以防止服务滥用
- 🕒 时区感知的日期/时间工具
- ⚠️ 强大的错误处理，支持自定义异常类型
- 🐳 Docker 化并通过环境变量配置
- ⚙️ 容器重启之间的配置持久化

## 快速开始

### 前提条件

- 在您的系统上安装了 Docker
- 一个正在运行的 SearXNG 实例（自托管或可访问的端点）

### 安装与使用

**构建 Docker 镜像：**
bash
docker build -t overtlids/mcp-searxng-enhanced:latest .


**使用您的 SearXNG 实例运行（手动 Docker 运行）：**
bash
docker run -i --rm --network=host 
  -e SEARXNG_ENGINE_API_BASE_URL="http://127.0.0.1:8080/search" 
  -e DESIRED_TIMEZONE="America/New_York" 
  overtlids/mcp-searxng-enhanced:latest

在此示例中，`SEARXNG_ENGINE_API_BASE_URL` 明确设置。`DESIRED_TIMEZONE` 也明确设置为 `America/New_York`，这与其默认值匹配。如果在 `docker run` 命令期间未通过 `-e` 标志提供环境变量，则服务器将自动使用其 `Dockerfile` 中定义的默认值（请参阅下面的环境变量表）。因此，如果您打算使用 `DESIRED_TIMEZONE` 的默认值，可以省略 `-e DESIRED_TIMEZONE="America/New_York"` 标志。但是，`SEARXNG_ENGINE_API_BASE_URL` 是关键性的，通常需要设置为与您的特定 SearXNG 实例地址相匹配，如果 `Dockerfile` 默认值 (`http://host.docker.internal:8080/search`) 不合适的话。

**关于手动 Docker 运行的注意事项：** 此命令独立运行 Docker 容器。如果您使用的是 MCP 客户端（如 VS Code 中的 Cline）来管理此服务器，客户端将根据 *其自己的配置* 启动容器实例。为了让 MCP 客户端使用特定的环境变量，它们 **必须** 在客户端为此服务器设置的配置中进行配置（见下文）。

**配置您的 MCP 客户端**（例如，VS Code 中的 Cline）：

为了使您的 MCP 客户端能够正确管理和运行此服务器，您 **必须** 在客户端针对 `overtlids/mcp-searxng-enhanced` 服务器的设置中定义所有必要的环境变量。MCP 客户端将使用这些设置来构造 `docker run` 命令。

以下是在您的 MCP 客户端 JSON 设置（例如 `cline_mcp_settings.json`）中推荐的此服务器的 **默认配置**。此示例明确列出了所有设置为其 `Dockerfile` 中定义的默认值的环境变量。您可以直接复制粘贴此内容，然后根据需要自定义任何值。

json
{
  "mcpServers": {
    "overtlids/mcp-searxng-enhanced": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network=host",
        "-e", "SEARXNG_ENGINE_API_BASE_URL=http://host.docker.internal:8080/search",
        "-e", "DESIRED_TIMEZONE=America/New_York",
        "-e", "ODS_CONFIG_PATH=/config/ods_config.json",
        "-e", "RETURNED_SCRAPPED_PAGES_NO=3",
        "-e", "SCRAPPED_PAGES_NO=5",
        "-e", "PAGE_CONTENT_WORDS_LIMIT=5000",
        "-e", "CITATION_LINKS=True",
        "-e", "MAX_IMAGE_RESULTS=10",
        "-e", "MAX_VIDEO_RESULTS=10",
        "-e", "MAX_FILE_RESULTS=5",
        "-e", "MAX_MAP_RESULTS=5",
        "-e", "MAX_SOCIAL_RESULTS=5",
        "-e", "TRAFILATURA_TIMEOUT=15",
        "-e", "SCRAPING_TIMEOUT=20",
        "-e", "CACHE_MAXSIZE=100",
        "-e", "CACHE_TTL_MINUTES=5",
        "-e", "CACHE_MAX_AGE_MINUTES=30",
        "-e", "RATE_LIMIT_REQUESTS_PER_MINUTE=10",
        "-e", "RATE_LIMIT_TIMEOUT_SECONDS=60",
        "-e", "IGNORED_WEBSITES=",
        "overtlids/mcp-searxng-enhanced:latest"
      ],
      "timeout": 60
    }
  }
}**MCP 客户端配置的关键点：**
- 上述示例提供了一整套参数，用于以所有环境变量设置为其默认值的方式运行 Docker 容器。
- 若要自定义任何设置，只需修改 MCP 客户端配置中 `args` 数组内相应的 `-e "VARIABLE_NAME=value"` 行的值即可。例如，要更改 `SEARXNG_ENGINE_API_BASE_URL` 和 `DESIRED_TIMEZONE`，则调整它们各自的行。
- 有关每个变量及其默认值的详细描述，请参阅下面的“环境变量”表。
- 服务器的行为主要由这些环境变量控制。虽然 `ods_config.json` 文件也可以影响设置（请参见配置管理），但通过 MCP 客户端传递的环境变量优先。

## 不使用 Docker 直接运行

如果您希望不使用 Docker 而直接使用 Python 运行服务器，请按照以下步骤操作：

**1. Python 安装：**
   - 此服务器需要 **Python 3.9 或更高版本**。推荐使用 Python 3.11（如 Docker 镜像中所使用的）。
   - 您可以从 [python.org](https://www.python.org/downloads/) 下载 Python。

**2. 克隆仓库：**
   - 从 GitHub 获取代码：
     bash
     git clone https://github.com/OvertliDS/mcp-searxng-enhanced.git
     cd mcp-searxng-enhanced
     

**3. 创建并激活虚拟环境（推荐）：**
   - 使用虚拟环境有助于管理依赖项，并避免与其他 Python 项目发生冲突。
     bash
     # 对于 Linux/macOS
     python3 -m venv .venv
     source .venv/bin/activate

     # 对于 Windows（命令提示符）
     python -m venv .venv
     ..venvScriptsactivate.bat

     # 对于 Windows（PowerShell）
     python -m venv .venv
     ..venvScriptsActivate.ps1
     

**4. 安装依赖项：**
   - 安装所需的 Python 包：
     bash
     pip install -r requirements.txt
     
     关键依赖项包括 `httpx`、`BeautifulSoup4`、`pydantic`、`trafilatura`、`python-dateutil`、`cachetools` 和 `zoneinfo`。

**5. 确保 SearXNG 可访问：**
   - 您仍然需要一个正在运行的 SearXNG 实例。确保您拥有其 API 基础 URL（例如 `http://127.0.0.1:8080/search`）。

**6. 设置环境变量：**
   - 服务器通过环境变量进行配置。至少，您可能需要设置 `SEARXNG_ENGINE_API_BASE_URL`。
   - **Linux/macOS (bash/zsh)：**
     bash
     export SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
     export DESIRED_TIMEZONE="America/Los_Angeles"
     
   - **Windows（命令提示符）：**
     bash
     set SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
     set DESIRED_TIMEZONE="America/Los_Angeles"
     
   - **Windows（PowerShell）：**
     bash
     $env:SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
     $env:DESIRED_TIMEZONE="America/Los_Angeles"
     
   - 有关所有可用选项，请参阅下面的“环境变量”表。如果未设置，则将使用脚本中的默认值或 `ods_config.json` 文件（如果在根目录或 `ODS_CONFIG_PATH` 指定的路径中存在）中的值。

**7. 运行服务器：**
   - 执行 Python 脚本：
     bash
     python mcp_server.py
     
   - 服务器将启动并通过 stdin/stdout 监听来自 MCP 客户端的连接。

**8. 配置文件 (`ods_config.json`)：**
   - 或者，您可以结合环境变量创建一个位于项目根目录（或 `ODS_CONFIG_PATH` 环境变量指定的路径）中的 `ods_config.json` 文件。环境变量始终优先于该文件中的值。示例：
    json
    {
      "searxng_engine_api_base_url": "http://127.0.0.1:8080/search",
      "desired_timezone": "America/New_York"
    }
    

## 环境变量以下环境变量控制服务器的行为。您可以在MCP客户端的配置中设置它们（推荐用于客户端管理的服务器），或者在手动运行Docker时设置。

| 变量                             | 描述                                | 默认值（来自Dockerfile）         | 备注                                                                                                |
|----------------------------------|-------------------------------------|----------------------------------|-----------------------------------------------------------------------------------------------------|
| `SEARXNG_ENGINE_API_BASE_URL`    | SearXNG搜索端点                    | `http://host.docker.internal:8080/search` | **对服务器操作至关重要**                                                                     |
| `DESIRED_TIMEZONE`               | 日期/时间工具的时区                | `America/New_York`               | 例如，`America/Los_Angeles`。时区数据库列表：https://en.wikipedia.org/wiki/List_of_tz_…