MCP搜索增强服务器

Name: MCP搜索增强服务器
Author: OvertliDS

作者：OvertliDS26 星标更新：2025-08-12

安装使用来源：spider==github.com

项目介绍

MCP SearXNG 增强服务器

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

功能

🔍 支持类别的 SearXNG 驱动的网络搜索（通用、图片、视频、文件、地图、社交媒体）
📄 网站内容抓取，包括引用元数据和自动转换 Reddit URL
📜 初始支持 PDF 阅读，并通过 PyMuPDF/PyMuPDF4LLM 转换为 Markdown
💾 内存缓存，带有自动新鲜度验证
🚦 基于域名的速率限制，防止服务滥用
🕒 支持时区的日期/时间工具
⚠️ 强大的错误处理机制，带有自定义异常类型
🐳 使用 Docker 化并可通过环境变量进行配置
⚙️ 在容器重启之间保持配置持久性

快速开始

先决条件

系统上已安装 Docker
运行中的 SearXNG 实例（自托管或可访问的端点）

安装及使用

构建 Docker 镜像：

docker build -t overtlids/mcp-searxng-enhanced:latest .

运行您的 SearXNG 实例（手动 Docker 运行）：

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 中定义的默认值。您可以直接复制粘贴此内容，然后根据需要自定义任何值。

{
  "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=1_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 容器。
要自定义任何设置，只需修改相应 -e "VARIABLE_NAME=value" 行内的 args 数组中的值即可。例如，要更改 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 下载 Python。

2. 克隆仓库：

从 GitHub 获取代码：

git clone https://github.com/OvertliDS/mcp-searxng-enhanced.git
cd mcp-searxng-enhanced

3. 创建并激活虚拟环境（推荐）：

使用虚拟环境有助于管理依赖项并避免与其他 Python 项目冲突。

# 对于 Linux/macOS
python3 -m venv .venv
source .venv/bin/activate

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

# 对于 Windows（PowerShell）
python -m venv .venv
.\.venv\Scripts\Activate.ps1

4. 安装依赖项：

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

5. 确保 SearXNG 可用：

您仍然需要一个运行中的 SearXNG 实例。确保您有其 API 基础 URL（例如，http://127.0.0.1:8080/search）。

6. 设置环境变量：

服务器通过环境变量进行配置。至少，您可能需要设置 SEARXNG_ENGINE_API_BASE_URL。

Linux/macOS（bash/zsh）：

export SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
export DESIRED_TIMEZONE="America/Los_Angeles"

Windows（命令提示符）：

set SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
set DESIRED_TIMEZONE="America/Los_Angeles"

Windows（PowerShell）：

$env:SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
$env:DESIRED_TIMEZONE="America/Los_Angeles"

请参阅下面的“环境变量”表，了解所有可用选项。如果没有设置，将使用脚本中的默认值或根目录或 ODS_CONFIG_PATH 所指定位置的 ods_config.json 文件中的值。

7. 运行服务器：

执行 Python 脚本：
```
python mcp_server.py
```
服务器将启动并监听 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_database_time_zones
`ODS_CONFIG_PATH`	持久配置文件的路径	`/config/ods_config.json`	通常在容器内保持默认值。
`RETURNED_SCRAPPED_PAGES_NO`	每次搜索返回的最大页面数	`3`
`SCRAPPED_PAGES_NO`	尝试抓取的最大页面数	`5`
`PAGE_CONTENT_WORDS_LIMIT`	每个抓取页面的最大单词数	`5000`
`CITATION_LINKS`	启用/禁用引用事件	`True`	`True` 或 `False`
`MAX_IMAGE_RESULTS`	返回的最大图像结果数	`10`
`MAX_VIDEO_RESULTS`	返回的最大视频结果数	`10`
`MAX_FILE_RESULTS`	返回的最大文件结果数	`5`
`MAX_MAP_RESULTS`	返回的最大地图结果数	`5`
`MAX_SOCIAL_RESULTS`	返回的最大社交媒体结果数	`5`
`TRAFILATURA_TIMEOUT`	内容提取超时（秒）	`15`
`SCRAPING_TIMEOUT`	HTTP 请求超时（秒）	`20`
`CACHE_MAXSIZE`	缓存网站的最大数量	`100`
`CACHE_TTL_MINUTES`	缓存生存时间（分钟）	`5`
`CACHE_MAX_AGE_MINUTES`	缓存内容的最大年龄（分钟）	`30`
`RATE_LIMIT_REQUESTS_PER_MINUTE`	每分钟每个域名的最大请求数	`10`
`RATE_LIMIT_TIMEOUT_SECONDS`	速率限制跟踪窗口（秒）	`60`
`IGNORED_WEBSITES`	忽略的站点的逗号分隔列表	`""` (空)	例如，`"example.com,another.org"`

配置管理

服务器采用三级配置方法：

脚本默认值（Python 中硬编码）
配置文件（从 ODS_CONFIG_PATH 加载，默认为 /config/ods_config.json）
环境变量（最高优先级）

只有在以下情况下才会更新配置文件：

文件尚未存在（首次初始化）
当前运行时显式提供了环境变量

这确保了用户配置在没有新环境变量的情况下，在容器重启之间得以保存。

工具及别名

工具名称	目的	别名
`search_web`	通过 SearXNG 进行网络搜索	`search`, `web_search`, `find`, `lookup_web`, `search_online`, `access_internet`, `lookup`*
`get_website`	抓取网站内容	`fetch_url`, `scrape_page`, `get`, `load_website`, `lookup`*
`get_current_datetime`	当前日期/时间	`current_time`, `get_time`, `current_date`

*lookup 是上下文敏感的：

如果调用时带有 url 参数，它映射到 get_website
否则，它映射到 search_web

示例：调用工具

网络搜索

{ "name": "search_web", "arguments": { "query": "开源人工智能" } }

或使用别名：

{ "name": "search", "arguments": { "query": "开源人工智能" } }

类别特定搜索

{ "name": "search_web", "arguments": { "query": "风景", "category": "images" } }

网站抓取

{ "name": "get_website", "arguments": { "url": "example.com" } }

或使用别名：

{ "name": "lookup", "arguments": { "url": "example.com" } }

当前日期/时间

{ "name": "get_current_datetime", "arguments": {} }

或：

{ "name": "current_time", "arguments": {} }

高级功能

类别特定搜索

search_web 工具支持不同类别并具有定制输出：

images: 返回图像 URL、标题和源页面，可选嵌入 Markdown
videos: 返回视频信息，包括标题、来源和嵌入 URL
files: 返回可下载文件信息，包括格式和大小
map: 返回位置数据，包括坐标和地址
social media: 返回来自社交平台的帖子和简介
general: 默认类别，抓取并返回完整网页内容

Reddit URL 转换

抓取 Reddit 内容时，URL 自动转换为使用旧版 reddit.com 域以获得更好的内容提取。

速率限制

基于域名的速率限制防止同一域名在一段时间内过多请求。这可以防止目标网站被淹没和潜在的 IP 封锁。

缓存验证

缓存的网站内容会根据其年龄自动验证新鲜度。过期的内容会自动刷新，而有效的缓存内容会被快速提供。

错误处理

服务器实现了一个强大的错误处理系统，具有以下异常类型：

MCPServerError: 所有服务器错误的基础异常类
ConfigurationError: 当配置值无效时抛出
SearXNGConnectionError: 当连接到 SearXNG 失败时抛出
WebScrapingError: 当网络抓取失败时抛出
RateLimitExceededError: 当域名的速率限制超出时抛出

错误会以具有信息性的消息传播到客户端。

故障排除

无法连接到 SearXNG: 确保您的 SearXNG 实例正在运行，并且 SEARXNG_ENGINE_API_BASE_URL 环境变量指向正确的端点。
速率限制错误: 如果遇到太多速率限制错误，调整 RATE_LIMIT_REQUESTS_PER_MINUTE。
慢内容提取: 如果内容提取速度慢，增加 TRAFILATURA_TIMEOUT 以允许更长时间处理复杂页面。
Docker 网络问题: 如果在 Windows/Mac 上使用 Docker Desktop，host.docker.internal 应解析为主机机器。在 Linux 上，您可能需要使用主机的 IP 地址。

致谢

灵感来源于：

[SearXNG](https://github.com/sear