内容
# mcp-searxng-local
[](LICENSE)
[](package.json)
[](https://github.com/dduartee/mcp-searxng-local/actions)
MCP 服务器，用于通过 [SearXNG](https://docs.searxng.org/) 进行网页搜索 — **零 API 密钥，零成本，100% 本地**。
## 前置条件
- [Node.js](https://nodejs.org) >= 20
- [Docker](https://docs.docker.com/get-docker/) + Docker Compose v2（推荐），**或** [Termux](https://termux.dev)（安卓）上的 Python 3.10+
## 快速开始
```bash
git clone https://github.com/dduartee/mcp-searxng-local
cd mcp-searxng-local
npm install && npm run build
docker compose up -d
# 验证
curl -s "http://localhost:4000/search?q=test&format=json" | python3 -c "import sys,json; print(len(json.load(sys.stdin).get('results',[])), 'results')"
```
有关 Termux（无 Docker）的详细信息，请参阅 [Termux 安装指南](docs/install-searxng-termux.md)。
## 工具
| 工具 | 描述 |
|------|-------------|
| `web_search` | 通过 Google、DuckDuckGo、Brave、Wikipedia、arXiv 进行搜索。支持域名/日期筛选、引擎选择。 |
| `web_search_advanced` | 与 `web_search` 相同 — 统一处理。提示 LLM 更谨慎地使用筛选器。 |
| `web_fetch` | 提取页面内容。`mode=highlights` 返回相关摘录（~98% 更小）。针对 GitHub URL 进行优化。 |
### `web_search` / `web_search_advanced` 参数
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `query` | 字符串 | *(必填)* | 搜索查询 |
| `count` | 数字 | `10` | 结果（1-50） |
| `pageno` | 数字 | `1` | 页码 |
| `categories` | 枚举 | — | `general`、`news`、`images`、`files`、`video`、`music` |
| `time_range` | 枚举 | — | `day`、`month`、`year` |
| `language` | 字符串 | — | `pt-BR`、`en-US` 等 |
| `includeDomains` | 字符串[] | — | 仅限这些域的结果 |
| `excludeDomains` | 字符串[] | — | 排除这些域 |
| `engines` | 字符串 | — | `google,duckduckgo,brave,wikipedia,arxiv` |
| `safesearch` | 数字 | — | `0`=关闭，`1`=适度，`2`=严格 |
| `startPublishedDate` | 字符串 | — | ISO 日期（客户端筛选） |
| `endPublishedDate` | 字符串 | — | ISO 日期（客户端筛选） |
### `web_fetch` 参数
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `url` | 字符串 | *(必填)* | 完整 URL |
| `maxChars` | 数字 | `5000` | 字符限制（100-50000） |
| `mode` | 枚举 | `text` | `text`（完整页面）或 `highlights`（相关摘录） |
| `query` | 字符串 | — | `highlights` 模式下必填 |
## 设置
添加配置后，**重启您的 MCP 客户端** 以使工具生效。
将 `/home/user/mcp-searxng-local` 替换为您的实际克隆路径。
### OpenCode
```bash
opencode mcp add mcp-searxng-local -- node /home/user/mcp-searxng-local/dist/index.js
```
```jsonc
// ./opencode.json（项目）或 ~/.config/opencode/opencode.json（全局）
{ "mcp": { "mcp-searxng-local": { "type": "local", "command": ["node", "/home/user/mcp-searxng-local/dist/index.js"] } } }
```
### Claude Code / Cursor / VS Code / Windsurf
```json
{
"mcpServers": {
"mcp-searxng-local": {
"command": "node",
"args": ["/home/user/mcp-searxng-local/dist/index.js"]
}
}
}
```
对于 VS Code，请使用 `"servers"` 代替 `"mcpServers"`。对于 Windsurf，配置位于 `~/.windsurf/mcp.json`。有关所有客户端配置，请参阅 [安装指南](docs/INSTALL.md)。
## 配置
所有环境变量均为可选 — 默认值适用于本地 SearXNG 端口 4000。
| 环境变量 | 默认值 | 描述 |
|---------|---------|-------------|
| `SEARXNG_HOST` | `localhost` | SearXNG 主机 |
| `SEARXNG_PORT` | `4000` | SearXNG 端口 |
| `SEARXNG_TIMEOUT` | `10000` | HTTP 超时（毫秒） |
| `SEARXNG_FALLBACK_URLS` | — | 以逗号分隔的公共 SearXNG URL（自动重试，当本地引擎被阻止时） |
| `GITHUB_TOKEN` | — | GitHub PAT — 将 API 请求限制从 60 提高到 5000 次/小时 |
| `DEBUG` | `false` | 启用详细日志记录 |
还接受 `MCP_SEARCH_LOCAL_` 前缀（例如 `MCP_SEARCH_LOCAL_SEARXNG_HOST`）。
服务器通过 `dotenv` 自动加载 `.env` 文件。
## 故障排除
| 症状 | 解决方法 |
|---------|-----|
| 工具未显示 | 运行 `npm run build`，验证 `dist/index.js` 存在 |
| `web_search` 连接错误 | SearXNG 未运行：`docker compose up -d` |
| `## 引擎无响应` | 自动回退处理此问题。添加 `SEARXNG_FALLBACK_URLS` 以获取更多选项 |
| 摘录返回完整页面 | 使用 `mode=text` 和较小的 `maxChars` |
有关完整的故障排除信息，请参阅 [安装指南](docs/INSTALL.md)。
## 文档
| 文档 | 描述 |
|-----|-------------|
| [安装指南](docs/INSTALL.md) | 本地、克隆、全局+插件和所有 MCP 客户端配置 |
| [Termux 安装](docs/install-searxng-termux.md) | SearXNG 原生安装在 Android 上 — 无 Docker |
| [架构](docs/ARCHITECTURE.md) | 请求流程、设计决策、目录结构 |
| [示例](docs/EXAMPLES.md) | JSON-RPC 有效载荷、代理工作流、CLI 测试 |
| [比较](docs/COMPARISON.md) | vs Exa、Brave、SearXNG 原始、Chrome DevTools |
| [GitHub 提取](docs/GITHUB_FETCH.md) | `web_fetch` 中优化的 GitHub URL 处理 |
| [搜索洞察](docs/SEARCH_INSIGHTS.md) | AI 代理实际需要从搜索中获取什么 |
## 许可证
MIT
