SearxNG MCP Server

SearxNG MCP 服务

一个使用 SearxNG 提供网页搜索功能的模型上下文协议（MCP）服务，让 Claude 等 AI 助手能够搜索网页。

由 AI 在人工监督下创建——因为有时连人工智能也需要有人提醒它该休息喝杯咖啡！🤖☕

概述

本项目实现了一个连接到 SearxNG 的 MCP 服务。SearxNG 是一个注重隐私的元搜索引擎。该服务提供了一种简单高效的方式，让大语言模型无需跟踪用户即可搜索网页。

该服务专为大语言模型设计，仅包含必要功能，以尽量减少上下文窗口的使用。这种精简的设计可确保大语言模型与搜索引擎之间高效通信，为更重要的信息留出宝贵的上下文空间。

功能

• 通过 SearxNG 进行注重隐私的网页搜索
• 便于大语言模型集成的简单 API
• 兼容 Claude Desktop 和其他符合 MCP 规范的客户端
• 可配置的搜索参数
• 针对大语言模型优化的整洁、格式化搜索结果

与兼容 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. 如果需要访问运行在 localhost 上的 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（服务器发送事件）：用于 Web 客户端和基于 HTTP 的集成

  • 启动客户端可连接的 HTTP 服务
  • 适用于需要实时更新的 Web 应用和服务
  • 使用 Docker 时需要进行端口映射

使用 SSE 传输

若要使用 SSE 传输协议：

1. 直接执行：

   # 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
   

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

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 # Transport protocol: stdio or 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 客户端集成：与 Claude Desktop 或其他符合 MCP 标准的客户端集成时，请使用使用 Docker部分所示的配置。

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 文件。