SearxNG MCP 服务器

一个使用 SearxNG 提供网络搜索能力的模型上下文协议（MCP）服务器，允许像 Claude 这样的AI助手进行网络搜索。

由人工智能创建并经人类监督——因为有时候即使人工智能也需要有人告诉它何时去休息一下！ 🤖☕

概述

该项目实现了一个连接到 SearxNG 的 MCP 服务器，SearxNG 是一个尊重隐私的元搜索引擎。该服务器为大型语言模型提供了一种简单高效的方式，在不追踪用户的情况下搜索网络。

该服务器特别设计用于 LLM，并仅包括基本功能以最小化上下文窗口的使用。这种精简的方法确保了 LLM 和搜索引擎之间的高效通信，保留了宝贵的上下文空间给更重要的信息。

功能

• 通过 SearxNG 进行隐私聚焦的网络搜索
• 用于 LLM 集成的简单 API
• 兼容 Claude Desktop 和其他符合 MCP 规范的客户端
• 可配置的搜索参数
• 清晰、格式化的搜索结果，优化用于 LLM

与 MCP 兼容应用程序的集成

集成示例

使用 pipx run（推荐，无需安装）

在您的主目录中创建一个 .clauderc 文件：

{
  "mcpServers": {
    "searxng": {
      "command": "pipx",
      "args": [
        "run", "searxng-simple-mcp@latest"
      ],
      "env": {
        "SEARXNG_MCP_SEARXNG_URL": "https://your-instance.example.com"
      }
    }
  }
}

使用 uvx run（无需安装）

{
  "mcpServers": {
    "searxng": {
      "command": "uvx",
      "args": [
        "run", "searxng-simple-mcp@latest"
      ],
      "env": {
        "SEARXNG_MCP_SEARXNG_URL": "https://your-instance.example.com"
      }
    }
  }
}

使用 Python 和 pip（需要安装）

{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["-m", "searxng_simple_mcp.server"],
      "env": {
        "SEARXNG_MCP_SEARXNG_URL": "https://your-instance.example.com"
      }
    }
  }
}

使用 Docker（无需安装）

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-e", "SEARXNG_MCP_SEARXNG_URL=http://localhost:8080",
        "ghcr.io/sacode/searxng-simple-mcp:latest"
      ]
    }
  }
}

注意： 当使用 Docker 运行 MCP 服务器时：

1. 必须直接使用 args 数组中的 -e 标志传递环境变量，因为 env 对象不会正确传递给 Docker 容器。
2. 如果您需要访问运行在本地主机上的 SearxNG 实例（例如 http://localhost:8080），必须使用 --network=host 标志来允许容器访问主机的网络。否则，“localhost” 在容器内部指的是容器本身，而不是您的主机机器。
3. 使用 --network=host 时，不需要端口映射（-p），并且会被忽略，因为容器直接共享主机的网络堆栈。

配置

使用环境变量配置服务器：

环境变量	描述	默认值
SEARXNG_MCP_SEARXNG_URL	要使用的 SearxNG 实例的 URL	https://paulgo.io/
SEARXNG_MCP_TIMEOUT	HTTP 请求超时时间（秒）	10
SEARXNG_MCP_DEFAULT_RESULT_COUNT	默认返回的结果数量	10
SEARXNG_MCP_DEFAULT_LANGUAGE	结果的语言代码（例如 'en', 'ru', 'all'）	all
SEARXNG_MCP_DEFAULT_FORMAT	结果的默认格式（'text', 'json'）	text
SEARXNG_MCP_LOG_LEVEL	日志级别（例如 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'）	ERROR
TRANSPORT_PROTOCOL	传输协议（'stdio' 或 'sse'）	stdio

注意： 设置日志级别高于 ERROR（如 DEBUG 或 INFO）可能会由于通信通道中的过多输出而破坏与某些应用程序的集成。

如果您不想自己托管，可以在 https://searx.space 找到公共 SearxNG 实例的列表。

安装及使用

前提条件

• Python 3.10 或更高版本
• 一个 SearxNG 实例（公共或自托管）

方案 1：无需安装运行（推荐）

最简单的使用此服务器的方法是使用 pipx 或 uvx，这允许您在不永久安装的情况下运行该包：

# 使用 pipx
pip install pipx  # 如果没有安装 pipx，请先安装
pipx run searxng-simple-mcp

# 或者使用 uvx
pip install uvx  # 如果没有安装 uvx，请先安装
uvx run searxng-simple-mcp

您可以直接传递配置选项：

# 使用 pipx 并指定自定义 SearxNG 实例
pipx run searxng-simple-mcp --searxng-url https://your-instance.example.com

方案 2：从 PyPI 或源码安装

对于更持久的安装：

# 从 PyPI 使用 pip 安装
pip install searxng-simple-mcp

# 或者使用 uv（更快的安装）
pip install uv
uv pip install searxng-simple-mcp

# 或者从源码安装
git clone https://github.com/Sacode/searxng-simple-mcp.git
cd searxng-simple-mcp
pip install uv
uv pip install -e .

安装后，您可以运行服务器：

# 安装后直接运行
python -m searxng_simple_mcp.server

# 或者带配置选项运行
python -m searxng_simple_mcp.server --searxng-url https://your-instance.example.com

方案 3：Docker

如果您更喜欢使用 Docker：

# 拉取 Docker 镜像
docker pull ghcr.io/sacode/searxng-simple-mcp:latest

# 使用默认设置运行容器（stdio 传输）
docker run --rm -i ghcr.io/sacode/searxng-simple-mcp:latest

# 使用环境文件配置运行
docker run --rm -i --env-file .env ghcr.io/sacode/searxng-simple-mcp:latest

# 使用 SSE 传输（启动 HTTP 服务器在 8000 端口）
docker run -p 8000:8000 -e TRANSPORT_PROTOCOL=sse ghcr.io/sacode/searxng-simple-mcp:latest

# 本地构建
docker build -t searxng-simple-mcp:local .
docker run --rm -i searxng-simple-mcp:local

# 使用 Docker Compose
docker-compose up -d

有关完整的 Docker 使用信息，请参阅下面的 Docker 配置 部分。

传输协议

MCP 服务器支持两种传输协议：

• STDIO（默认）：适用于 CLI 应用程序和直接集成

  • 在所有示例中默认使用
  • 适合与 Claude Desktop 和其他符合 MCP 规范的客户端集成
  • 不会启动 HTTP 服务器

• SSE（服务器发送事件）：适用于基于 Web 的客户端和基于 HTTP 的集成

  • 启动客户端可以连接的 HTTP 服务器
  • 对于需要实时更新的 Web 应用和服务非常有用
  • 使用 Docker 时需要端口映射

使用 SSE 传输

要使用 SSE 传输协议：

1. 直接执行：

   # 将传输协议设置为 SSE
   TRANSPORT_PROTOCOL=sse python -m searxng_simple_mcp.server
   
   # 或者使用 FastMCP
   fastmcp run src/searxng_simple_mcp/server.py --transport sse
   

2. 使用 Docker：

   # 使用 SSE 传输协议运行
   docker run -p 8000:8000 -e TRANSPORT_PROTOCOL=sse -e SEARXNG_MCP_SEARXNG_URL=https://your-instance.example.com ghcr.io/sacode/searxng-simple-mcp:latest
   

3. 使用 Docker Compose（从包含的 docker-compose.yml）：

   environment:
     - SEARXNG_MCP_SEARXNG_URL=https://searx.info
     - SEARXNG_MCP_TIMEOUT=10
     - SEARXNG_MCP_MAX_RESULTS=20
     - SEARXNG_MCP_LANGUAGE=all
     - TRANSPORT_PROTOCOL=sse # 传输协议：stdio 或 sse
   

使用 SSE 时，默认情况下服务器可通过 HTTP 访问 http://localhost:8000。

要从 MCP 客户端连接到 SSE 服务器，可以使用如下配置：

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

注意： 并非所有应用程序都支持 SSE 传输协议。在使用此传输方法之前，请确保您的 MCP 客户端兼容 SSE。

开发

对于开发和测试：

# 安装依赖项
uv pip install -e .

# 运行 linter 和格式化工具
ruff check .
ruff check --fix .
ruff format .

# 直接运行服务器
python -m src.searxng_simple_mcp.server

# 或者使用 FastMCP
fastmcp run src/searxng_simple_mcp/server.py  # 使用 stdio 传输（默认）
fastmcp run src/searxng_simple_mcp/server.py --transport sse  # 使用 sse 传输

# 在开发模式下运行（启动 MCP Inspector）
fastmcp dev src/searxng_simple_mcp/server.py

发布到 PyPI

对于需要发布新版本包到 PyPI 的维护人员：

# 安装开发依赖项
npm run install:deps

# 清理、构建并检查包
npm run build:package
npm run check:package

# 发布到 PyPI（需要 PyPI 凭证）
npm run publish:pypi

# 或者使用一键命令更新版本并发布
npm run publish:patch  # 增加补丁版本（1.0.1 -> 1.0.2）
npm run publish:minor  # 增加次要版本（1.0.1 -> 1.1.0）
npm run publish:major  # 增加主要版本（1.0.1 -> 2.0.0）

这些命令将：

1. 更新 package.json 和 pyproject.toml 中的版本
2. 清理 dist 目录以移除旧的构建
3. 构建包（创建 wheel 和源分布）
4. 检查包是否有错误
5. 将包上传到 PyPI

您需要有一个 PyPI 账户并通过 twine 进行身份验证。可以通过以下方式设置身份验证：

• 在您的主目录中创建一个 .pypirc 文件
• 使用环境变量（TWINE_USERNAME 和 TWINE_PASSWORD）
• 使用 PyPI API 令牌（推荐）

Docker 配置

当使用 Docker 运行 MCP 服务器时，请记住以下几点：

1. 与 MCP 客户端的集成：使用 使用 Docker 部分所示的配置与 Claude Desktop 或其他符合 MCP 规范的客户端集成。

2. 传输协议：

   • 默认情况下，Docker 容器使用 stdio 传输协议
   • 对于 SSE 传输，请参阅 使用 SSE 传输 部分

3. 配置选项：

   • 使用环境文件（.env）配置服务器：docker run --env-file .env ...
   • 使用 -e 标志传递单个环境变量：docker run -e SEARXNG_MCP_SEARXNG_URL=https://example.com ...
   • 参阅 配置 部分了解可用的环境变量

4. 网络：

   • 当需要访问主机上的服务时，使用 --network=host
   • 当暴露 SSE 服务器到网络时，使用 -p 8000:8000

包结构

searxng-simple-mcp/
├── src/
│   ├── run_server.py         # 入口脚本
│   └── searxng_simple_mcp/   # 主包
├── docker-compose.yml        # Docker Compose 配置
├── Dockerfile                # Docker 配置
└── pyproject.toml            # Python 项目配置

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目根据 MIT 许可证发布 - 详情见 LICENSE 文件。