MCP SearXNG 增强版

MCP SearXNG 增强服务器

一个模型上下文协议 (MCP) 服务器，用于分类感知的网页搜索、网站抓取和日期/时间工具。旨在与 SearXNG 和现代 MCP 客户端无缝集成。

特征

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

快速入门

先决条件

您的系统上安装了 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标志提供DESIRED_TIMEZONE变量，则服务器将自动使用其Dockerfile中定义的默认值（请参阅下面的环境变量表）。因此，如果您打算使用DESIRED_TIMEZONE的默认值，则可以省略-e DESIRED_TIMEZONE="America/New_York"标志。但是， SEARXNG_ENGINE_API_BASE_URL至关重要，如果 Dockerfile 默认值（ http://host.docker.internal:8080/search ）不合适，通常需要将其设置为与您的特定 SearXNG 实例的地址匹配。

**关于手动 Docker Run 的注意事项：**此命令将独立运行 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=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）

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

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 项目发生冲突。
# For Linux/macOS python3 -m venv .venv source .venv/bin/activate # For Windows (Command Prompt) python -m venv .venv .\.venv\Scripts\activate.bat # For 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 。

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.json文件（如果位于根目录或ODS_CONFIG_PATH中）中的默认值。

7.运行服务器：

执行 Python 脚本：
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` 。tz 数据库时区列表： 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": "open source ai" } }

或使用别名：

{ "name": "search", "arguments": { "query": "open source ai" } }

特定类别搜索

{ "name": "search_web", "arguments": { "query": "landscapes", "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工具支持具有定制输出的不同类别：

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

Reddit URL 转换

在抓取 Reddit 内容时，URL 会自动转换为使用 old.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 - 尊重隐私的元搜索引擎
Trafilatura - 用于文本提取的网页抓取工具
ihor-sokoliuk/mcp-searxng - SearXNG 的原始 MCP 服务器
nnaoycurt （更好的网络搜索工具）
@bwoodruff2021 （ GetTimeDate工具）

MCP SearXNG Enhanced

Integrations