SearxNG MCP 服务器

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

由 AI 在人类监督下创建 - 因为有时即使是人工智能也需要有人告诉它什么时候该休息一下喝杯咖啡！🤖☕

概述

该项目实现了一个连接到 SearxNG（一种尊重隐私的元搜索引擎）的 MCP 服务器。该服务器提供了一种简单且高效的方法，使大型语言模型能够在不跟踪用户的情况下进行网络搜索。

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

特性

• 通过 SearxNG 实现注重隐私的网络搜索
• 简单的 API 便于 LLM 集成
• 兼容 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. 必须直接使用 -e 标志在 args 数组中传递环境变量，因为 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，这允许您在不永久安装的情况下运行该包：

# Using pipx
pip install pipx  # Install pipx if you don't have it
pipx run searxng-simple-mcp

# OR using uvx
pip install uvx  # Install uvx if you don't have it
uvx run searxng-simple-mcp

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

# Using pipx with custom SearxNG instance
pipx run searxng-simple-mcp --searxng-url https://your-instance.example.com

选项 2：从 PyPI 或源代码安装

对于更永久的安装：

# From PyPI using pip
pip install searxng-simple-mcp

# OR using uv (faster installation)
pip install uv
uv pip install searxng-simple-mcp

# OR from source
git clone https://github.com/Sacode/searxng-simple-mcp.git
cd searxng-simple-mcp
pip install uv
uv pip install -e .

安装后，您可以使用以下命令运行服务器：

# Run directly after installation
python -m searxng_simple_mcp.server

# OR with configuration options
python -m searxng_simple_mcp.server --searxng-url https://your-instance.example.com

选项 3：Docker

如果您更喜欢使用 Docker：

# Pull the Docker image
docker pull ghcr.io/sacode/searxng-simple-mcp:latest

# Run the container with default settings (stdio transport)
docker run --rm -i ghcr.io/sacode/searxng-simple-mcp:latest

# Run with environment file for configuration
docker run --rm -i --env-file .env ghcr.io/sacode/searxng-simple-mcp:latest

# Run with SSE transport (starts HTTP server on port 8000)
docker run -p 8000:8000 -e TRANSPORT_PROTOCOL=sse ghcr.io/sacode/searxng-simple-mcp:latest

# Building locally
docker build -t searxng-simple-mcp:local .
docker run --rm -i searxng-simple-mcp:local

# Using Docker Compose
docker-compose up -d

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

传输协议

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

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

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

• SSE（Server-Sent Events）：适用于基于 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://localhost:8000 访问服务器。

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

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

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

开发

用于开发和测试：

# Install dependencies
uv pip install -e .

# Run linter and formatter
ruff check .
ruff check --fix .
ruff format .

# Run the server directly
python -m src.searxng_simple_mcp.server

# OR using FastMCP
fastmcp run src/searxng_simple_mcp/server.py  # Use stdio transport (default)
fastmcp run src/searxng_simple_mcp/server.py --transport sse  # Use sse transport

# Run in development mode (launches MCP Inspector)
fastmcp dev src/searxng_simple_mcp/server.py

发布到 PyPI

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

# Install development dependencies
npm run install:deps

# Clean, build, and check the package
npm run build:package
npm run check:package

# Publish to PyPI (requires PyPI credentials)
npm run publish:pypi

# Alternatively, use the all-in-one commands to update version and publish
npm run publish:patch  # Increments patch version (1.0.1 -> 1.0.2)
npm run publish:minor  # Increments minor version (1.0.1 -> 1.1.0)
npm run publish:major  # Increments major version (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         # Entry point script
│   └── searxng_simple_mcp/   # Main package
├── docker-compose.yml        # Docker Compose configuration
├── Dockerfile                # Docker configuration
└── pyproject.toml            # Python project configuration

贡献

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

许可证

本项目根据 MIT 许可证授权 - 详情请参阅 LICENSE 文件。