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

配置管理

服务器使用三层配置方法：

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

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

• 文件尚不存在（首次初始化）
• 当前运行时明确提供了环境变量

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

工具与别名

*lookup 是上下文敏感的：

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

示例：调用工具

网络搜索
json
{ "name": "search_web", "arguments": { "query": "open source ai" } }

或使用别名：
json
{ "name": "search", "arguments": { "query": "open source ai" } }

特定类别的搜索
json
{ "name": "search_web", "arguments": { "query": "landscapes", "category": "images" } }

网站抓取
json
{ "name": "get_website", "arguments": { "url": "example.com" } }

或使用别名：
json
{ "name": "lookup", "arguments": { "url": "example.com" } }

获取当前日期/时间
json
{ "name": "get_current_datetime", "arguments": {} }

或：
json
{ "name": "current_time", "arguments": {} }

高级功能

特定类别的搜索

search_web 工具支持不同的类别，并提供定制化的输出：

• images: 返回图片 URL、标题和源页面，可选 Markdown 嵌入
• videos: 返回视频信息，包括标题、来源和嵌入 URL
• files: 返回可下载文件的信息，包括格式和大小
• map: 返回位置数据，包括坐标和地址
• social media: 返回来自社交媒体平台的帖子和个人资料
• 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 工具)

许可证

MIT License © 2025 OvertliDS