MCP SearXNG Enhanced

](https://mseep.ai/app/overtlids-mcp-searxng-enhanced)

MCP SearXNG增强型服务器

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

特性

• 🔍 SearXNG支持类别搜索（一般、图像、视频、文件、地图、社交媒体）
• 📄 使用引文元数据和自动Reddit URL转换进行网站内容抓取
• 📜 初始PDF阅读支持，可使用Markdown转换 PyMuPDF/PyMuPDF4LLM
• 💾 具有自动新鲜度验证的内存缓存
• 🚦 基于域的速率限制，防止服务滥用
• 🕒 时区感知日期/时间工具
• ⚠️ 使用自定义异常类型进行稳健的错误处理
• 🐳 通过环境变量进行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，与默认值匹配。如果未使用提供环境变量 -e 旗帜在 docker run 命令，服务器将自动使用其 Dockerfile （请参阅下面的环境变量表）。因此，如果您打算使用默认值 DESIRED_TIMEZONE，你可以省略 -e DESIRED_TIMEZONE="America/New_York" 旗帜。然而， SEARXNG_ENGINE_API_BASE_URL 这是至关重要的，如果Dockerfile默认值为，通常需要设置为与您的特定SearXNG实例的地址相匹配(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=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 MCP客户端配置中的数组。例如，更改 SEARXNG_ENGINE_API_BASE_URL 和 DESIRED_TIMEZONE，您将调整它们各自的线条。
• 有关每个变量及其默认值的详细说明，请参阅下表“环境变量”。
• 服务器的行为主要由这些环境变量控制。虽然A ods_config.json 文件还可以影响设置（请参阅配置管理），MCP客户端传递的环境变量优先。

HTTP服务器模式（FastMCP）

除了默认的stdio传输外，服务器还可以使用以下方式通过HTTP公开MCP端点 FastMCP。这对于通过HTTP连接而不是生成子进程的客户端很有用。

启动HTTP服务器

python mcp_server.py --http

服务器将于启动 0.0.0.0:8000 默认情况下，在以下位置接受MCP请求：

http://:
/mcp

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

HTTP服务器环境变量

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

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）

如果你更喜欢在没有Docker的情况下直接使用Python运行服务器，请按照以下步骤操作：

1.Python安装：

• 此服务器需要 Python 3.9或更高版本建议使用Python 3.11（如Docker镜像中使用的）。
• 你可以从以下网址下载Python python.org.

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

服务器在以下位置启动FastMCP HTTP端点 http://0.0.0.0:8000/mcp。参见 HTTP服务器模式 用于配置选项。

8.配置文件(ods_config.json):

• 或者，或者与环境变量结合，您可以创建 ods_config.json 项目根目录中的文件（或由指定的路径） ODS_CONFIG_PATH 环境变量）。环境变量将始终优先于此文件中的值。例子：

{ "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 对上下文敏感：

• 如果打电话给a 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 该工具支持不同类别的定制输出：

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

Reddit URL转换

抓取Reddit内容时，URL会自动转换为使用旧的.redit.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桌面， host.docker.internal 应解析到主机。在Linux上，您可能需要使用主机的IP地址。
• 无法访问HTTP模式：确保没有防火墙阻止 MCP_HTTP_PORT （默认值 8000).集 MCP_HTTP_HOST=0.0.0.0 绑定所有接口，或 127.0.0.1 仅限于本地主机。
• HTTP模式会话ID错误：服务器以无状态HTTP模式运行——每次POST到 /mcp 是自给自足的。如果您的客户端需要基于会话的传输，请切换到stdio模式。

致谢

灵感来源：

• SearXNG -尊重隐私的元搜索引擎
• 特拉菲拉图拉 -用于文本提取的Web抓取工具
• sokoliuk/mcp searxng -SearXNG的原始MCP服务器

许可证

麻省理工学院许可证©2025 OverliDS