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 下载 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时设置。