MCP 服务器

SearxNG MCP Server

提供使用 SearxNG 的网络搜索功能，允许像 Claude 这样的人工智能助手使用尊重隐私的元搜索引擎进行网络搜索。

Tools

web_search

Performs a web search using SearxNG and returns formatted results. Results are returned in either text format (human-readable) or JSON format depending on the result_format parameter selected.

README

SearxNG MCP 服务器

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

由 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"
      }
    }
  }
}

使用带有 pip 的 Python（需要安装）

{
  "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 服务器一起使用时：

环境变量必须使用 args 数组中的 -e 标志直接传递，因为 env 对象无法正确传递到 Docker 容器。
如果您需要访问在 localhost 上运行的 SearxNG 实例（例如，http://localhost:8080），则必须使用 --network=host 标志以允许容器访问主机的网络。否则，容器内的“localhost”将引用容器本身，而不是您的主机。
使用 --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 或源代码安装

对于更永久的安装：

# 使用 pip 从 PyPI 安装
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 传输（在端口 8000 上启动 HTTP 服务器）
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 传输协议：

直接执行：

# 将传输协议设置为 SSE
TRANSPORT_PROTOCOL=sse python -m searxng_simple_mcp.server

# 或者使用 FastMCP
fastmcp run src/searxng_simple_mcp/server.py --transport sse

使用 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

使用 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 和 formatter
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)

这些命令将：

更新 package.json 和 pyproject.toml 中的版本
清理 dist 目录以删除旧版本
构建软件包（创建 wheel 和源分发）
检查软件包是否存在错误
将软件包上传到 PyPI

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

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

Docker 配置

将 Docker 与 MCP 服务器一起使用时，请记住以下几点：

与 MCP 客户端集成：使用使用 Docker 部分中显示的配置与 Claude Desktop 或其他符合 MCP 协议的客户端集成。
传输协议：
- 默认情况下，Docker 容器使用 stdio 传输协议
- 对于 SSE 传输，请参见使用 SSE 传输部分
配置选项：
- 使用环境变量文件 (.env) 来配置服务器：docker run --env-file .env ...
- 使用 -e 标志传递单个环境变量：docker run -e SEARXNG_MCP_SEARXNG_URL=https://example.com ...
- 有关可用的环境变量，请参见配置部分
网络：
- 当您需要访问主机上的服务时，请使用 --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 文件。