SearXNG MCP Server

SearXNG MCP 服务

一种 MCP SSE 实现：集成了 SearXNG 的模型上下文协议（MCP）服务，为 AI Agent 提供强大且尊重隐私的搜索能力。

---

概览

本项目演示了如何构建一个 MCP 服务，让 AI Agent 使用 SearXNG 实例执行网页搜索。它以 SearXNG 作为后端，为创建自己的 MCP 服务提供了实用模板。

本实现遵循 Anthropic 制定的 MCP 服务构建最佳实践，可与任何兼容 MCP 的客户端无缝集成。

---

前置条件

• Python 3.9+
• 可访问正在运行的 SearXNG 实例（本地或远程）
• Docker（可选，用于容器化部署）
• uv（可选，用于快速管理 Python 依赖项）
• Smithery（可选，用于管理 MCP 服务）

SearXNG 服务（必需）

你必须拥有正在运行且可访问的 SearXNG 服务。推荐通过 Docker 运行：

docker run -d --name=searxng -p 32768:8080 -v "/root/searxng:/etc/searxng" \
  -e "BASE_URL=http://0.0.0.0:32768/" \
  -e "INSTANCE_NAME=home" \
  --restart always searxng/searxng

• 这将在端口 32768 上运行 SearXNG，并将配置持久化到 /root/searxng。
• MCP 服务默认预期 SearXNG 可通过 http://172.17.0.1:32768 访问（参见 .env）。

---

安装

使用 uv

如果尚未安装 uv，请先安装：

pip install uv

克隆此仓库：

git clone https://github.com/The-AI-Workshops/searxng-mcp-server.git
cd searxng-mcp-server/dev/searXNG-mcp

安装依赖项：

uv pip install -r requirements.txt

根据提供的示例创建 .env 文件：

nano .env
# Edit .env as needed

在 .env 文件中配置环境变量（参见“配置”部分）。

---

使用 Docker（推荐）

构建 Docker 镜像：

docker build -t mcp/searxng-mcp .

创建 .env 文件并配置环境变量。

---

运行 Docker 镜像：

docker run -d --env-file ./.env -p 32769:32769 mcp/searxng-mcp

---

使用 Smithery

Smithery 是一款用于管理 AI Agent 工具和 MCP 服务的命令行工具。

如果尚未安装 Smithery，请先安装（各种安装方式请参见 Smithery 文档，例如使用 pipx）：

pipx install smithery

使用 Smithery 安装 SearXNG MCP 服务：

smithery install @The-AI-Workshops/searxng-mcp-server

这会将该服务及其依赖项安装到 Smithery 管理的专用环境中。

安装完成后，Smithery 会提供已安装服务的路径。你需要进入此目录进行配置。例如，如果 Smithery 将工具安装到 ~/.smithery/tools/，路径可能是 ~/.smithery/tools/The-AI-Workshops/searxng-mcp-server。

通过复制示例，在服务目录中创建 .env 文件：

# Example:
# cd ~/.smithery/tools/The-AI-Workshops/searxng-mcp-server
cp .env.example .env
nano .env
# Edit .env as needed

在 .env 文件中配置环境变量（参见“配置”部分）。

---

配置

可在 .env 文件中配置以下环境变量：

变量	描述	示例
SEARXNG_BASE_URL	SearXNG 实例的基础 URL	http://172.17.0.1:32768
HOST	使用 SSE 传输时绑定的主机	0.0.0.0
PORT	使用 SSE 传输时监听的端口	32769
TRANSPORT	传输协议（sse 或 stdio）	sse

---

运行服务

使用 uv

SSE 传输

在 .env 中设置 TRANSPORT=sse，然后：

uv run dev/searXNG-mcp/server.py

Stdio 传输

使用 stdio 时，MCP 客户端本身可以启动 MCP 服务，因此此时无需运行任何命令。

---

使用 Docker

SSE 传输

docker build -t mcp/searxng-mcp .
docker run --rm -it -p 32769:32769 --env-file dev/searXNG-mcp/.env -v $(pwd)/dev/searXNG-mcp:/app mcp/searxng-mcp

• -v $(pwd)/dev/searXNG-mcp:/app 挂载允许你在主机上实时编辑代码和 .env 文件，并让更改反映到正在运行的容器中。
• 服务将在 http://localhost:32769/sse 上提供。

Stdio 传输

使用 stdio 时，MCP 客户端本身可以启动 MCP 服务容器，因此此时无需运行任何内容。

---

使用 Smithery 运行

SSE 传输

在 Smithery 安装的服务目录中的 .env 文件里设置 TRANSPORT=sse。 然后，通常可以使用 Smithery 为该工具创建的虚拟环境中的 Python 解释器运行服务：

# Navigate to the server directory, e.g.,
# cd ~/.smithery/tools/The-AI-Workshops/searxng-mcp-server
~/.smithery/venvs/The-AI-Workshops_searxng-mcp-server/bin/python server.py

或者，如果 Smithery 为已安装的工具提供了直接运行命令（请查阅 Smithery 文档）：

smithery run @The-AI-Workshops/searxng-mcp-server

服务将根据 .env 中的 HOST 和 PORT 设置提供访问（例如，http://localhost:32769/sse）。

Stdio 传输

使用 stdio 时，MCP 客户端本身会启动服务。客户端配置需要指向 Smithery 管理目录中的 server.py 脚本，可使用 smithery exec 或工具虚拟环境中的 Python 解释器直接路径。示例请参阅“与 MCP 客户端集成”部分。

---

与 MCP 客户端集成

SSE 配置

使用 SSE 传输启动服务后，可以使用以下配置连接：

{
  "mcpServers": {
    "searxng": {
      "transport": "sse",
      "url": "http://localhost:32769/sse"
    }
  }
}

**Windsurf 用户注意：**请在配置中使用 serverUrl，而不是 url：

{
  "mcpServers": {
    "searxng": {
      "transport": "sse",
      "serverUrl": "http://localhost:32769/sse"
    }
  }
}

**n8n 用户注意：**请使用 host.docker.internal，而不是 localhost，因为 n8n 需要从自己的容器外部访问主机：

因此，MCP 节点中的完整 URL 应为：http://host.docker.internal:32769/sse

如果使用的端口不是默认的 32769，请务必更新端口。

---

使用 Stdio 配置 Python

将此服务添加到 Claude Desktop、Windsurf 或其他 MCP 客户端的配置中：

{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["dev/searXNG-mcp/server.py"],
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://localhost:32768",
        "HOST": "0.0.0.0",
        "PORT": "32769"
      }
    }
  }
}

---

使用 Stdio 配置 Docker

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-e", "TRANSPORT",
               "-e", "SEARXNG_BASE_URL",
               "-e", "HOST",
               "-e", "PORT",
               "mcp/searxng-mcp"],
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://localhost:32768",
        "HOST": "0.0.0.0",
        "PORT": "32769"
      }
    }
  }
}

---

使用 Stdio 配置 Smithery

如果你使用 Smithery 安装了服务，可以将 MCP 客户端配置为通过 stdio 运行该服务。Smithery 提供了 exec 命令，可在工具环境中运行可执行文件。

{
  "mcpServers": {
    "searxng": {
      "command": "smithery",
      "args": ["exec", "@The-AI-Workshops/searxng-mcp-server", "--", "python", "server.py"],
      // "cwd" (current working directory) might be automatically handled by Smithery.
      // If server.py is in a subdirectory, adjust the python script path e.g., "python", "path/to/server.py"
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://localhost:32768", // Adjust as needed
        "HOST": "0.0.0.0", // Typically not used by stdio server itself but good to set
        "PORT": "32769"  // Typically not used by stdio server itself
      }
    }
  }
}

或者，你可以找到 Smithery 创建的虚拟环境中的 Python 解释器路径（例如，~/.smithery/venvs/The-AI-Workshops_searxng-mcp-server/bin/python）以及 server.py 的路径（例如，~/.smithery/tools/The-AI-Workshops/searxng-mcp-server/server.py），并直接使用这些路径：

{
  "mcpServers": {
    "searxng": {
      "command": "~/.smithery/venvs/The-AI-Workshops_searxng-mcp-server/bin/python",
      "args": ["~/.smithery/tools/The-AI-Workshops/searxng-mcp-server/server.py"],
      // "cwd" should be the directory containing server.py if not using absolute paths for args,
      // or if server.py relies on relative paths for other files (like .env).
      // Example: "cwd": "~/.smithery/tools/The-AI-Workshops/searxng-mcp-server",
      "env": {
        "TRANSPORT": "stdio",
        "SEARXNG_BASE_URL": "http://localhost:32768"
        // Other necessary env vars from .env can be duplicated here
      }
    }
  }
}

确保路径适用于你的 Smithery 安装，并且 server.py 能找到 .env 文件（通常可以将 cwd 设置为服务的根目录，或者确保 server.py 从绝对路径加载该文件，前提是 Smithery 设置了该路径）。

---

构建你自己的服务

此模板为构建更复杂的 MCP 服务提供了基础。若要构建自己的服务：

• 使用 @mcp.tool() 装饰器创建方法，添加自己的工具
• 创建自己的生命周期函数，以添加所需的依赖项（客户端、数据库连接等）
• 还可以使用 @mcp.resource() 和 @mcp.prompt() 添加提示词和资源

---

SearXNG 搜索工具参数

search 工具支持以下参数（除 q 外均为可选参数）：

• q（必填）：搜索查询字符串。
• categories：以逗号分隔的启用搜索类别列表。
• engines：以逗号分隔的启用搜索引擎列表。
• language：语言代码。
• page：搜索页码（默认值：1）。
• time_range：[day, month, year]
• format：[json, csv, rss]（默认值：json）
• results_on_new_tab：[0, 1]
• image_proxy：[true, false]
• autocomplete：[google, dbpedia, duckduckgo, mwmbl, startpage, wikipedia, stract, swisscows, qwant]
• safesearch：[0, 1, 2]
• theme：[simple]
• enabled_plugins：启用的插件列表。
• disabled_plugins：禁用的插件列表。
• enabled_engines：启用的引擎列表。
• disabled_engines：禁用的引擎列表。

更多详情请参阅 SearXNG 文档。

---

许可证

MIT 许可证