ihor-sokoliuk/mcp-searxng

## 快速开始 将其添加到您的 MCP 客户端配置中（例如 `claude_desktop_config.json`）： ``` { "mcpServers": { "searxng": { "command": "npx", "args": ["-y", "mcp-searxng"], "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL" } } } } ``` 将 `YOUR_SEARXNG_INSTANCE_URL` 替换为您的 SearXNG 实例的 URL（例如 `https://searxng.example.com`）。 ## 功能 - **网络搜索**：支持分页的常规查询、新闻和文章搜索。 - **结构化搜索输出**：通过 `response_format` 选择格式化文本或原始 SearXNG 格式的 JSON。 - **直接回答与元数据**：文本结果会在结果列表之前优先展示 SearXNG 的直接回答、纠错、建议和 infoboxes。 - **搜索建议**：通过 SearXNG 的 `/autocompleter` endpoint 提供查询自动补全。 - **实例能力发现**：从 `/config` 检查已配置的 categories、engines、默认设置、locales 和 plugins。 - **URL 内容读取**：具有分页、section 过滤和 heading 提取功能的高级内容提取。 - **智能缓存**：使用 TTL（Time-To-Live）缓存 URL 内容，以提高性能并减少冗余请求。 - **分页**：控制要检索的结果页码。 - **时间过滤**：按时间范围（天、周、月、年）过滤结果。 - **语言选择**：按首选语言过滤结果。 - **Safe Search**：控制搜索结果的内容过滤级别。 - **相关性过滤**：使用 `min_score` 过滤掉低分的搜索结果。 ## 为什么选择 mcp-searxng？ | | Brave MCP | Exa MCP | Firecrawl MCP | **mcp-searxng** | |--|:---------:|:-------:|:-------------:|:---------------:| | Web Search | ✓ | ✓ | ✓ | ✓ | | Read URL | ✗ | ✓ | ✓ | ✓ | | Pagination | ✗ | ✗ | ✓ | ✓ | | Self-hosted | ✗ | ✗ | Partial | ✓ | | Privacy | ✗ | ✗ | ✗ | ✓ | | Free / No API key | ✗ | ✗ | ✗ | ✓ | ## 工作原理 `mcp-searxng` 是一个独立的 MCP server —— 一个独立的 Node.js 进程，您的 AI 助手通过连接它来进行网络搜索。它通过 HTTP JSON API 查询任何 SearXNG 实例。 ``` AI Assistant (e.g. Claude) │ MCP protocol ▼ mcp-searxng (this project — Node.js process) │ HTTP JSON API (SEARXNG_URL) ▼ SearXNG instance ``` ## 工具 - **searxng_web_search** - 支持分页执行网络搜索 - 输入： - `query` (string)：搜索查询。此字符串将传递给外部搜索服务。 - `pageno` (number, optional)：搜索页码，从 1 开始（默认为 1） - `time_range` (string, optional)：按时间范围过滤结果 - 可选值之一："day"、"week"、"month"、"year"（默认：无） - `language` (string, optional)：结果的语言代码（例如："en"、"fr"、"de"）或 "all"（默认："all"） - `safesearch` (number, optional)：Safe Search 过滤级别（0：None，1：Moderate，2：Strict）（默认：实例设置） - `min_score` (number, optional)：最低相关性分数，范围从 0.0 到 1.0。低于此分数的结果将被过滤掉。 - `num_results` (number, optional)：返回的最大结果数量，从 1 到 20。`SEARXNG_MAX_RESULTS` 作为操作上限适用。 - `categories` (string, optional)：逗号分隔的 SearXNG categories（例如 `"news"`、`"it,science"`）。当实时的 `/config` 可用时，值会被修剪并忽略大小写规范化为实例的规范 category 名称；未知的值将被拒绝并列出可用的 categories。如果 `/config` 不可用，值将原样转发并附带警告。默认：SearXNG 实例默认值。 - `engines` (string, optional)：逗号分隔的 SearXNG engine 名称（例如 `"google,bing,ddg"`、`"semantic scholar"`）。当实时的 `/config` 可用时，值会被修剪并忽略大小写规范化为规范的 engine 名称，包括默认禁用的 engines；未知的值将被拒绝并列出可用的 engines。如果 `/config` 不可用，值将原样转发并附带警告。 - `response_format` (string, optional)：响应格式，`"text"` 表示格式化的 agent 可读输出，或 `"json"` 表示带有已过滤/切片 `results` 的原始 SearXNG JSON。（默认：`"text"`） - **searxng_search_suggestions** - 获取自动补全建议以优化搜索查询 - 输入： - `query` (string)：要自动补全的部分或完整查询。 - `language` (string, optional)：建议的语言代码（例如："en"、"fr"、"de"）或 "all"（默认："all"） - **searxng_instance_info** - 发现已配置的 SearXNG 实例公开的 categories、engines、默认设置、locales 和 plugins - 输入： - `includeEngines` (boolean, optional)：在响应中包含已启用的 engine 名称。（默认：false） - `includeDisabled` (boolean, optional)：当 `includeEngines` 为 true 时，包含已禁用的 engine 名称。（默认：false） - `category` (string, optional)：将 categories 和 engines 过滤为单个 category 名称。 - `refresh` (boolean, optional)：绕过进程缓存并获取最新的 `/config` 数据。（默认：false） - **web_url_read** - 读取 URL 内容并将其转换为 markdown，具有高级内容提取选项 - 输入： - `url` (string)：要获取和处理的 URL - `startChar` (number, optional)：内容提取的起始字符位置（默认：0） - `maxLength` (number, optional)：返回的最大字符数 - `section` (string, optional)：提取特定 heading 下的内容（搜索 heading 文本） - `paragraphRange` (string, optional)：返回特定的段落范围（例如：'1-5'、'3'、'10-'） - `readHeadings` (boolean, optional)：仅返回 heading 列表而不是完整内容 ## 安装

NPM (全局安装)

``` npm install -g mcp-searxng ``` ``` { "mcpServers": { "searxng": { "command": "mcp-searxng", "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL" } } } } ```

Docker

**预构建镜像：** ``` docker pull isokoliuk/mcp-searxng:latest ``` 镜像签名可以使用 Cosign 进行验证 —— 有关说明，请参阅 [SECURITY.md](SECURITY.md)。 ``` { "mcpServers": { "searxng": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "SEARXNG_URL", "isokoliuk/mcp-searxng:latest" ], "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL" } } } } ``` 要传递额外的环境变量，请在 `args` 中添加 `-e VAR_NAME`，并在 `env` 中添加该变量。 **本地构建：** ``` docker build -t mcp-searxng:latest -f Dockerfile . ``` 使用与上述相同的配置，将 `isokoliuk/mcp-searxng:latest` 替换为 `mcp-searxng:latest`。

Docker Compose

`docker-compose.yml`： ``` services: mcp-searxng: image: isokoliuk/mcp-searxng:latest stdin_open: true environment: - SEARXNG_URL=YOUR_SEARXNG_INSTANCE_URL # Add optional variables as needed — see CONFIGURATION.md ``` MCP 客户端配置： ``` { "mcpServers": { "searxng": { "command": "docker-compose", "args": ["run", "--rm", "mcp-searxng"] } } } ```

HTTP 传输

默认情况下，服务器使用 STDIO。设置 `MCP_HTTP_PORT` 以启用 HTTP 模式： ``` { "mcpServers": { "searxng-http": { "command": "mcp-searxng", "env": { "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL", "MCP_HTTP_PORT": "3000" } } } } ``` **Endpoints：** `POST/GET/DELETE /mcp`（MCP 协议），`GET /health`（健康检查） **测试：** ``` MCP_HTTP_PORT=3000 SEARXNG_URL=http://localhost:8080 mcp-searxng curl http://localhost:3000/health ```

## 配置 将 `SEARXNG_URL` 设置为您的 SearXNG 实例 URL。所有其他变量均为可选。 完整的环境变量参考：[CONFIGURATION.md](CONFIGURATION.md) ## 故障排除 ### 来自 SearXNG 的 403 Forbidden 您的 SearXNG 实例可能禁用了 JSON 格式。编辑 `settings.yml`（通常位于 `/etc/searxng/settings.yml`）： ``` search: formats: - html - json ``` 重启 SearXNG（`docker restart searxng`），然后验证： ``` curl 'http://localhost:8080/search?q=test&format=json' ``` 您应该会收到 JSON 响应。如果没有，请确认文件已正确挂载且 YAML 缩进有效。 另请参阅：[SearXNG 设置文档](https://docs.searxng.org/admin/settings/settings.html) · [讨论](https://github.com/searxng/searxng/discussions/1789) ## Star 历史 ## 许可证 MIT —— 有关详细信息，请参阅 [LICENSE](LICENSE)。

标签：AI助手, MCP, MITM代理, SearXNG, 工具集成, 数据接入, 暗色界面, 网络搜索, 自动化攻击, 请求拦截