MCP SearXNG Enhanced Server

MCP SearXNG Enhanced 服务

用于按类别进行网页搜索、抓取网站内容以及提供日期／时间工具的模型上下文协议（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 至关重要；如果 Dockerfile 中的默认值（http://host.docker.internal:8080/search）不适用，通常需要将其设置为与你的 SearXNG 实例地址相匹配的值。

**手动运行 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=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 客户端传递的环境变量具有更高优先级。

HTTP 服务模式（FastMCP）

除了默认的 stdio 传输方式外，服务还可以使用 FastMCP 通过 HTTP 暴露 MCP 端点。这适用于通过 HTTP 连接，而非启动子进程的客户端。

启动 HTTP 服务

python mcp_server.py --http

服务默认会在 0.0.0.0:8000 上启动，并在以下地址接受 MCP 请求：

http://<host>:<port>/mcp

允许所有来源（CORS 完全开放），因此任何客户端或基于浏览器的工具都可以访问该端点。

HTTP 服务环境变量

变量	描述	默认值
MCP_HTTP_HOST	绑定的主机地址	0.0.0.0
MCP_HTTP_PORT	监听的端口	8000

示例 — 自定义主机和端口：

MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=9000 python mcp_server.py --http

Windows（命令提示符）：

set MCP_HTTP_HOST=127.0.0.1
set MCP_HTTP_PORT=9000
python mcp_server.py --http

Windows（PowerShell）：

$env:MCP_HTTP_HOST="127.0.0.1"
$env:MCP_HTTP_PORT="9000"
python mcp_server.py --http

通过 HTTP 连接 MCP 客户端

将 MCP 客户端指向 /mcp 端点：

{
  "mcpServers": {
    "mcp-searxng-enhanced-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

注意： 所有服务配置变量（SEARXNG_ENGINE_API_BASE_URL、DESIRED_TIMEZONE 等）在 HTTP 模式下的作用与 stdio 模式完全相同。服务开始接受连接前，会在启动时写入 ods_config.json 文件。

---

原生运行（不使用 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、filetype、pymupdf、pymupdf4llm 和 fastmcp。

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. 运行服务：

• stdio 模式（默认——适用于会启动子进程的 MCP 客户端）：

  python mcp_server.py
  

  服务通过 stdin/stdout 监听 MCP 客户端连接。

• HTTP 模式（适用于通过 HTTP 连接的 MCP 客户端）：

  python mcp_server.py --http
  

  服务会在 http://0.0.0.0:8000/mcp 启动 FastMCP HTTP 端点。配置选项请参阅 HTTP 服务模式。

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

Variable	描述	默认值（来自 Dockerfile）	备注
SEARXNG_ENGINE_API_BASE_URL	SearXNG 搜索端点	http://host.docker.internal:8080/search	对服务运行至关重要
MCP_HTTP_HOST	HTTP 服务模式的绑定地址	0.0.0.0	仅在使用 --http 启动时使用
MCP_HTTP_PORT	HTTP 服务模式的端口	8000	仅在使用 --http 启动时使用
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"

配置管理

服务采用三层配置方式：

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

仅在以下情况下更新配置文件：

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

这样可确保在未设置新环境变量时，用户配置在容器重启后仍会保留。

工具与别名

工具名称	用途	别名
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 工具支持不同类别，并提供相应的输出：

• 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 地址。
• 无法访问 HTTP 模式：请确保防火墙未阻止 MCP_HTTP_PORT（默认为 8000）。设置 MCP_HTTP_HOST=0.0.0.0 以绑定所有接口，或设置 127.0.0.1 以仅允许 localhost 访问。
• HTTP 模式会话 ID 错误：服务以无状态 HTTP 模式运行——对 /mcp 的每个 POST 请求都是独立的。如果客户端需要基于会话的传输方式，请改用 stdio 模式。

致谢

灵感来源：

• SearXNG - 尊重隐私的元搜索引擎
• Trafilatura - 用于文本提取的网页抓取工具
• ihor-sokoliuk/mcp-searxng - 最初的 SearXNG MCP 服务
• nnaoycurt (更好的网页搜索工具)
• @bwoodruff2021 (获取日期时间工具)

许可证

MIT 许可证 © 2025 OvertliDS