使用说明

SearxNG MCP服务器

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

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

概述

该项目实现了一个连接到SearxNG的MCP服务器，SearxNG是一个尊重隐私的元搜索引擎。该服务器为大型语言模型提供了一种简单有效的方法来搜索网络，而无需跟踪用户。

该服务器是专门为LLM设计的，只包括基本功能，以最大限度地减少上下文窗口的使用。这种简化的方法确保了LLM和搜索引擎之间的高效通信，为更重要的信息保留了宝贵的上下文空间。

特性

通过SearxNG进行以隐私为中心的网络搜索
用于LLM集成的简单API
与Claude Desktop和其他符合MCP的客户端兼容
可配置的搜索参数
针对LLM优化的干净、格式化的搜索结果

与MCP兼容的应用程序集成

集成示例

使用管道管路（推荐，无需安装）

创建一个 .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"
      ]
    }
  }
}

注：在MCP服务器上使用Docker时：

必须使用直接传递环境变量 -e 旗在 args 数组，如 env 对象未正确传递到Docker容器。
如果您需要访问在本地主机上运行的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_LOGLEVEL	日志记录级别（例如，“调试”、“信息”、“警告”、“错误”、“严重”）	错误
TRANSPORT_PROTOCOL	传输协议（“dio”或“sse”）	stdio

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

您可以在以下网址找到公共SearxNG实例的列表 https://searx.space 如果你不想举办自己的。

安装与使用

先决条件

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服务器支持两种传输协议：

标准输入输出 （默认）：用于CLI应用程序和直接集成
- 在所有示例中默认使用
- 适用于与Claude Desktop和其他符合MCP的客户端集成
- 未启动HTTP服务器
SSE （服务器发送事件）：用于基于web的客户端和基于HTTP的集成
- 启动客户端可以连接的HTTP服务器
- 适用于需要实时更新的web应用程序和服务
- 使用Docker时需要端口映射

使用SSE传输

要使用SSE传输协议：

直接执行:

# Set the transport protocol to SSE
TRANSPORT_PROTOCOL=sse python -m searxng_simple_mcp.server

# Or with FastMCP
fastmcp run src/searxng_simple_mcp/server.py --transport sse

使用Docker:

# Run with SSE transport protocol
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 # Transport protocol: stdio or sse

使用SSE时，服务器将可通过HTTP访问 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)

这些命令将：

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

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

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

Docker配置

在MCP服务器上使用Docker时，请记住以下几点：

与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 当您需要访问主机上的服务时
- 使用 -p 8000:8000 将SSE服务器暴露到网络时

封装结构

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

贡献

欢迎投稿！请随时提交拉取请求。

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。