内容
# SearXNG MCP 服务器
使用 SearXNG 作为 MCP 服务器的桥梁，来自 Claude Code。
**[日语版 README 请参见这里](README.ja.md)**
## 功能
- **searxng_search**: 多引擎网页搜索
- **searxng_images**: 图片搜索
- **searxng_news**: 新闻搜索
## 前提条件
1. 运行 SearXNG 实例并启用 JSON 格式
**重要**: SearXNG 的默认配置只允许 HTML 格式。要使用此 MCP 服务器，您必须通过挂载自定义配置文件来启用 JSON 格式。
首先，从示例文件创建您的配置文件:
```bash
cp searxng-config/settings.yml.example searxng-config/settings.yml
# 编辑 settings.yml 以设置您自己的 secret_key
```
然后使用该配置文件启动 SearXNG:
```bash
# 使用 Docker（推荐）
docker run -d \
-p 8080:8080 \
-v $(pwd)/searxng-config/settings.yml:/etc/searxng/settings.yml:ro \
-e SEARXNG_BASE_URL=http://localhost:8080/ \
searxng/searxng
# 或本地安装
# 请参见：https://docs.searxng.org/admin/installation.html
```
`searxng-config/settings.yml.example` 文件包含启用 JSON 格式所需的配置:
```yaml
use_default_settings: true
search:
formats:
- html
- json
server:
secret_key: "your-secret-key-here"
limiter: false
image_proxy: true
```
2. 验证 SearXNG 已启用 JSON 格式
```bash
curl "http://localhost:8080/search?q=test&format=json"
```
如果您收到 `403 Forbidden` 错误，则 JSON 格式未启用。请确保您已正确挂载配置文件。
## 安装
```bash
cd searxng-mcp-server
npm install
npm run build
```
## Claude Code 配置
### 方法 1: 使用 CLI（推荐）
```bash
# 添加到本地作用域（当前项目）
claude mcp add --transport stdio searxng -- node /path/to/searxng-mcp-server/dist/index.js
# 添加到用户作用域（所有项目）
claude mcp add --transport stdio searxng --scope user -- node /path/to/searxng-mcp-server/dist/index.js
```
添加环境变量:
```bash
claude mcp add --transport stdio searxng \
--env SEARXNG_BASE_URL=http://localhost:8080 \
-- node /path/to/searxng-mcp-server/dist/index.js
```
### 方法 2: 手动配置
**项目作用域** (`。mcp.json` 在项目根目录):
```json
{
"mcpServers": {
"searxng": {
"command": "node",
"args": ["/path/to/searxng-mcp-server/dist/index.js"],
"env": {
"SEARXNG_BASE_URL": "http://localhost:8080"
}
}
}
}
```
**用户作用域** (`~/.claude.json`):
```json
{
"mcpServers": {
"searxng": {
"command": "node",
"args": ["/path/to/searxng-mcp-server/dist/index.js"],
"env": {
"SEARXNG_BASE_URL": "http://localhost:8080"
}
}
}
}
```
### 验证安装
```bash
# 列出已配置的 MCP 服务器
claude mcp list
# 在 Claude Code 中
/mcp
```
## 自动批准工具调用（可选）
默认情况下，Claude Code 在每次调用 SearXNG 工具时都会询问确认。要跳过确认，请在 `~/.claude/settings.json` 中添加以下内容:
```json
{
"permissions": {
"allow": [
"mcp__searxng__searxng_search",
"mcp__searxng__searxng_images",
"mcp__searxng__searxng_news"
]
}
}
```
## 环境变量
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `SEARXNG_BASE_URL` | `http://localhost:8080` | SearXNG 服务器 URL |
## 使用示例
从 Claude Code:
### 网页搜索
```text
使用 SearXNG 搜索“Rust 编程语言特性”
```
### 图片搜索
```text
使用 SearXNG 查找“富士山”的图片
```
### 新闻搜索
```text
使用 SearXNG 获取有关“AI 发展”的最新新闻
```
## 故障排除
### JSON 格式出现 403 Forbidden 错误
如果您在使用 `format=json` 时收到 `403 Forbidden` 错误，则 SearXNG 实例中未启用 JSON 格式。请确保:
1. 启动 Docker 时挂载配置文件:
```bash
docker run -d \
-p 8080:8080 \
-v $(pwd)/searxng-config/settings.yml:/etc/searxng/settings.yml:ro \
-e SEARXNG_BASE_URL=http://localhost:8080/ \
searxng/searxng
```
2. 验证配置是否包含 JSON 格式:
```bash
docker exec <container_id> grep -A 3 "formats" /etc/searxng/settings.yml
```
### 无法连接到 SearXNG
```bash
# 检查 SearXNG 是否正在运行
curl "http://localhost:8080/search?q=test&format=json"
# 如果未运行（Docker）- 确保挂载配置文件
docker run -d \
-p 8080:8080 \
-v $(pwd)/searxng-config/settings.yml:/etc/searxng/settings.yml:ro \
-e SEARXNG_BASE_URL=http://localhost:8080/ \
searxng/searxng
```
### 没有返回结果
SearXNG 从多个搜索引擎聚合结果。如果没有返回结果:
1. 检查您的 SearXNG 实例是否启用了搜索引擎
2. 尝试指定搜索引擎：`engines: "google,bing,duckduckgo"`
3. 检查 SearXNG 日志中的错误
### MCP 服务器未显示
```bash
# 验证服务器是否已注册
claude mcp list
# 检查服务器健康状况
claude mcp get searxng
```
## 许可证
MIT
