Searxng Mul Mcp

中文 | Deutsch | English | Español | français | 日本語 | 한국어 | Português | Русский

SearXNG Mul MCP

用于集成 SearXNG 元搜索引擎的模型上下文协议（MCP）服务，支持通过 stdio 和 HTTP 传输协议进行多查询并行搜索。

🌟 推荐：OllaMan - 功能强大的 Ollama AI 模型管理器。

功能特性

• ✅ 多查询并行搜索：同时执行多个搜索查询，提高效率
• ✅ 双传输协议支持：兼容 stdio 和 HTTP MCP 传输协议
• ✅ SearXNG API 集成：直接集成 SearXNG REST API，无需浏览器自动化
• ✅ 基本身份验证：支持启用了基本身份验证的 SearXNG 服务
• ✅ Docker 部署：通过 Docker 和 Docker Compose 实现完整容器化
• ✅ 环境配置：通过环境变量灵活管理配置

快速开始

NPM 用法

Stdio 模式（默认）

SEARXNG_URL=https://your.searxng.com npx -y searxng-mul-mcp

HTTP 模式

SEARXNG_URL=https://your.searxng.com npx -y searxng-mul-mcp --transport=http --host=0.0.0.0 --port=3000

环境变量

# Required: SearXNG server URL
SEARXNG_URL=https://your.searxng.com

# Optional: Basic Auth credentials
USERNAME=your_username
PASSWORD=your_password

# Optional: Transport configuration (can also use CLI flags)
TRANSPORT=stdio|http
HOST=0.0.0.0        # HTTP mode only
PORT=3000           # HTTP mode only

# Optional: Debug mode
DEBUG=false

配置

Claude Desktop 配置

将以下配置添加到 Claude Desktop 的 claude_desktop_config.json 文件中：

stdio 模式：

{
  "mcpServers": {
    "searxng-mul-mcp": {
      "command": "npx",
      "args": ["-y", "searxng-mul-mcp"],
      "env": {
        "SEARXNG_URL": "https://your.searxng.com",
        "USERNAME": "your_username",
        "PASSWORD": "your_password"
      }
    }
  }
}

SearXNG 服务设置

此 MCP 服务需要访问一个 SearXNG 实例。你可以：

1. 使用公共 SearXNG 实例（例如 https://your.searxng.com）
2. 部署自己的 SearXNG 服务
3. 使用启用了基本身份验证的私有 SearXNG 实例

基本身份验证

如果你的 SearXNG 服务需要基本身份验证：

export USERNAME=your_username
export PASSWORD=your_password

传输协议

Stdio 传输

• MCP 客户端集成的默认模式
• 使用标准输入/输出进行通信
• 适用于直接连接 MCP 客户端

HTTP 传输

• 提供 StreamableHTTP JSON-RPC 接口（协议版本 2025-03-26）
• 在 /health 提供健康检查端点
• 在 /mcp 提供用于客户端通信的 MCP 端点
• 支持会话管理并自动清理
• 完整支持跨源请求的 CORS
• 适用于基于 Web 的集成和现代 MCP 客户端

安装

从源代码安装

git clone <repository-url>
cd searxng-mul-mcp
npm install
npm run build
npm start

Docker 部署

创建 docker-compose.yml 文件：

services:
  searxng-mul-mcp:
    image: ghcr.io/jae-jae/searxng-mul-mcp:latest
    environment:
      - SEARXNG_URL=https://your.searxng.com
      # Optional: Basic Auth
      # - USERNAME=your_username
      # - PASSWORD=your_password
    ports:
      - "3000:3000"

运行：

docker-compose up -d

MCP 工具用法

此服务提供一个 search 工具，接受以下参数：

参数

• queries（必需）：要并行执行的搜索查询字符串数组
• engines（可选）：要使用的特定搜索引擎（例如，“google”、“bing”、“duckduckgo”）
• categories（可选）：用于筛选结果的搜索类别（例如，“general”、“images”、“news”）
• safesearch（可选）：安全搜索级别（0=关闭，1=中等，2=严格）
• language（可选）：搜索语言代码（例如，“en”、“zh”、“es”）

开发

前置条件

• Node.js 18 或更高版本
• npm 或 yarn
• TypeScript

构建命令

# Install dependencies
npm install

# Build TypeScript
npm run build

# Start development server
npm run dev

# Run in production
npm start

# Clean build directory
npm run clean

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

项目结构

searxng-mul-mcp/
├── src/
│   ├── index.ts                 # Application entry point
│   ├── server.ts               # MCP server core logic
│   ├── config/
│   │   └── index.ts            # Configuration management
│   ├── tools/
│   │   ├── index.ts            # Tool definitions
│   │   └── searxng.ts          # SearXNG search tool implementation
│   ├── transports/
│   │   ├── index.ts            # Transport factory
│   │   ├── stdio.ts            # Stdio transport implementation
│   │   ├── http.ts             # HTTP transport implementation
│   │   └── types.ts            # Transport type definitions
│   ├── services/
│   │   └── searxng-api.ts      # SearXNG API client
│   └── utils/
│       └── logger.ts           # Logging utilities
├── build/                      # TypeScript compilation output
├── package.json               # Project dependencies and scripts
├── tsconfig.json              # TypeScript configuration
├── Dockerfile                 # Docker image build
├── docker-compose.yml         # Docker Compose configuration
└── README.md                  # This file

API 参考

SearXNG API 集成

此服务集成了 SearXNG 搜索 API。有关 SearXNG API 功能的更多信息，请参阅：https://docs.searxng.org/dev/search_api.html

错误处理

此服务实现了全面的错误处理：

• 网络错误：自动重试机制（最多 3 次）
• 身份验证错误：针对身份验证失败提供清晰的错误消息
• API 速率限制：平稳降级并报告错误
• 超时处理：可配置请求超时时间（默认：30 秒）

监控

健康检查

HTTP 模式提供健康检查端点：

curl http://localhost:3000/health

响应：

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0.0"
}

日志记录

服务器提供结构化日志记录，并支持配置日志级别：

• ERROR：严重错误和故障
• WARN：警告消息和功能降级
• INFO：常规运行信息
• DEBUG：详细的调试信息（使用 DEBUG=true 启用）

故障排除

常见问题

1. 连接失败：检查 SEARXNG_URL 和网络连接
2. 身份验证错误：检查 Basic Auth 的 USERNAME 和 PASSWORD
3. 端口已被占用：在 HTTP 模式下更改 PORT 环境变量
4. 搜索超时：延长超时时间或检查 SearXNG 服务器性能

调试模式

启用调试日志以便详细排查问题：

DEBUG=true npx searxng-mul-mcp

许可证

MIT License - 详情请参阅 LICENSE 文件。

贡献

1. Fork 此代码库
2. 创建功能分支
3. 进行更改
4. 根据需要添加测试
5. 提交拉取请求

支持

如有问题或疑问：

1. 查看故障排除部分
2. 查阅 SearXNG 文档
3. 在 GitHub 上提交问题