搜索索引MCP服务器
项目介绍
SearXNG MCP 服务器
这是一个与 SearXNG 集成的 Model Context Protocol (MCP) 服务器实现，旨在为AI代理提供强大且尊重隐私的搜索能力。
概述
本项目展示了如何构建一个MCP服务器，使AI代理能够通过SearXNG实例执行网络搜索。它作为创建您自己的MCP服务器的实际模板，使用SearXNG作为后端。
该实现遵循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
# 根据需要编辑.env
在.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代理工具及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文件：
# 示例：
# cd ~/.smithery/tools/The-AI-Workshops/searxng-mcp-server
cp .env.example .env
nano .env
# 根据需要编辑.env
在.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客户端本身可以启动服务器容器，因此此时无需运行任何内容。
使用Smithery运行
SSE 传输
在Smithery安装的服务器目录中设置.env中的TRANSPORT=sse。
然后，您可以通常使用Smithery为工具创建的虚拟环境中的Python解释器来运行服务器：
# 导航到服务器目录，例如，
# 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。
Python与Stdio配置
将此服务器添加到Claude Desktop、Windsurf或其他任何MCP客户端的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"
}
}
}
}
Docker与Stdio配置
{
"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"
}
}
}
}
Smithery与Stdio配置
如果您使用Smithery安装了服务器，您可以配置您的MCP客户端通过stdio运行它。Smithery提供了一个exec命令来在其工具环境中运行可执行文件。
{
"mcpServers": {
"searxng": {
"command": "smithery",
"args": ["exec", "@The-AI-Workshops/searxng-mcp-server", "--", "python", "server.py"],
// "cwd"（当前工作目录）可能会被Smithery自动处理。
// 如果server.py位于子目录中，调整Python脚本路径，例如："python", "path/to/server.py"
"env": {
"TRANSPORT": "stdio",
"SEARXNG_BASE_URL": "http://localhost:32768", // 根据需要调整
"HOST": "0.0.0.0", // 通常stdio服务器本身不使用，但设置好是有益的
"PORT": "32769" // 通常stdio服务器本身不使用
}
}
}
}
或者，您可以找到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"应为包含server.py的目录，如果不使用绝对路径，则为args，
// 或者如果server.py依赖于相对路径的其他文件（如.env）。
// 示例："cwd": "~/.smithery/tools/The-AI-Workshops/searxng-mcp-server",
"env": {
"TRANSPORT": "stdio",
"SEARXNG_BASE_URL": "http://localhost:32768"
// 其他必要的.env变量可以在这里重复
}
}
}
}
确保路径对您的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 许可证