内容
# 搜索引擎工具 MCP
一个用于网页搜索和提取的Python MCP（模型上下文协议）服务器，支持多个提供商。
## 版本
当前版本：**0.4.3**
## 功能
- 🔍 **网页搜索**：使用You.com或Tavily API进行网页搜索
- 📄 **内容提取**：从任何URL提取干净的内容（免费本地提取或Tavily API）
- 🔄 **自动提供商选择**：自动选择最佳可用提供商
- 🔑 **可选API密钥**：无需API密钥即可使用本地提取（Tavily需要API密钥以增强提取）
- 🚀 **MCP兼容**：完全支持模型上下文协议
## 安装
### 从PyPI（推荐）
✅ **最新版本0.4.3现已在PyPI上可用！**
**PyPI软件包页面：** https://pypi.org/project/search-engine-tool-mcp/0.4.3/
```bash
# 使用pip
pip install search-engine-tool-mcp==0.4.3
# 或使用uv（推荐）
uv pip install search-engine-tool-mcp==0.4.3
# 或使用uvx（无需安装）
uvx --from search-engine-tool-mcp==0.4.3 search-engine-tool-mcp
```
### 从源码
```bash
git clone https://github.com/YiHarvest/search-engine-tool.git
cd search-engine-tool
# 使用uv（推荐）
uv sync
# 或使用pip
pip install -e .
```
## 配置
### 环境变量
- **SEARXNG_BASE_URL**（推荐）：您的SearXNG实例URL。例如：`http://127.0.0.1:8080`
- **TALORDATA_API_KEY**（推荐）：您的TalorData SERP API密钥，用于网页搜索。在[https://dashboard.talordata.com](https://dashboard.talordata.com)获取。
- **YDC_API_KEY**（推荐）：您的You.com API密钥。在[https://you.com/platform](https://you.com/platform)获取。
- **TAVILY_API_KEY**（可选）：您的Tavily API密钥，用于高级功能和备用提取。
**自动提供商选择逻辑：**
对于**网页搜索**：
- 如果存在TALORDATA_API_KEY → 使用TalorData（SERP API提供商）
- 如果TalorData失败或返回空结果 → 回退到Tavily或You.com
- 否则，如果存在SEARXNG_BASE_URL → 使用SearXNG（免费，自托管）
- 如果SearXNG失败或返回空结果 → 回退到TalorData，Tavily或You.com
- 否则，如果存在YDC_API_KEY或YOU_API_KEY → 使用You.com
- 否则，如果存在TAVILY_API_KEY → 使用Tavily
- 如果未配置 → 抛出错误
对于**网页提取**：
- 默认提供商是`local`（免费，无需API密钥）
- 如果提供商为“auto”，本地提取失败：
- 如果可用，则回退到Tavily
- 否则返回错误
- 如果提供商为“tavily” → 需要`TAVILY_API_KEY`
- **注意：** TalorData不支持网页提取
### 快速配置
1. 复制示例配置文件：
```bash
cp .env.example .env
```
2. 编辑`.env`文件并填写您的API密钥：
```bash
YDC_API_KEY="your-ydc-api-key-here"
TAVILY_API_KEY="your-tavily-api-key-here"
SEARXNG_BASE_URL="http://127.0.0.1:8080"
TALORDATA_API_KEY="your-talordata-api-key-here"
```
### 或手动设置环境变量
```bash
# 设置SearXNG基准URL（推荐用于免费自托管搜索）
export SEARXNG_BASE_URL="http://127.0.0.1:8080"
# 设置TalorData API密钥（推荐用于SERP API搜索）
export TALORDATA_API_KEY="your-talordata-api-key"
# 设置You.com API密钥（替代）
export YDC_API_KEY="ydc-sk-your-api-key"
# 或设置Tavily API密钥（替代）
export TAVILY_API_KEY="tvly-your-api-key"
```
### 运行SearXNG本地
`SEARXNG_BASE_URL`不是API密钥。它是您运行的SearXNG实例的URL。此MCP服务器使用SearXNG的JSON搜索端点，因此必须在`settings.yml`中启用`json`。
1. 创建配置文件目录和`searxng/settings.yml`：
```bash
mkdir -p searxng
```
```yml
# searxng/settings.yml
use_default_settings: true
search:
formats:
- html
- json
server:
# 替换此项，即使在本地使用：openssl rand -hex 32
secret_key: "replace-with-a-random-secret"
limiter: false
image_proxy: true
```
2. 启动绑定到localhost的SearXNG容器：
```bash
docker run -d \
--name searxng \
--restart unless-stopped \
-p 127.0.0.1:8080:8080 \
-v "$(pwd)/searxng:/etc/searxng:rw" \
docker.io/searxng/searxng:latest
```
3. 验证JSON端点：
```bash
curl "http://127.0.0.1:8080/search?q=hello&format=json"
```
验证返回包含`results`的JSON后，配置：
```bash
SEARXNG_BASE_URL="http://127.0.0.1:8080"
```
使用`docker stop searxng`和`docker start searxng`停止和重启它。对于生产或公共部署，请添加反向代理，HTTPS，访问控制和随机`secret_key`；请参阅[官方SearXNG容器文档](https://docs.searxng.org/admin/installation-docker.html)。
### MCP客户端配置
必须将凭证作为环境变量传递给MCP服务器进程。下面所有值均为占位符。仅保留您使用的提供商，永远不要将真实凭证提交到Git。
#### Trae（JSON）
在Trae的MCP设置中添加或导入以下配置：
```json
{
"mcpServers": {
"search-engine-tool": {
"command": "uvx",
"args": [
"--from",
"search-engine-tool-mcp==0.4.3",
"search-engine-tool-mcp"
],
"env": {
"TALORDATA_API_KEY": "your-talordata-api-key",
"TALORDATA_BASE_URL": "https://serpapi.talordata.net/serp/v1/request",
"SEARXNG_BASE_URL": "http://127.0.0.1:8080",
"YDC_API_KEY": "your-you-api-key",
"TAVILY_API_KEY": "tvly-your-tavily-api-key"
}
}
}
}
```
保存后重启或刷新MCP服务器。如果Trae和SearXNG在不同的主机或容器网络上运行，则`127.0.0.1`指的是运行Trae/MCP进程的环境；请将其替换为从该环境可达的SearXNG URL。
#### Codex（TOML）
Codex CLI和Codex IDE扩展程序共享`config.toml`。将以下内容添加到用户配置文件`~/.codex/config.toml`或受信任项目中的`.codex/config.toml`：
```toml
[mcp_servers.search-engine-tool]
command = "uvx"
args = [
"--from",
"search-engine-tool-mcp==0.4.3",
"search-engine-tool-mcp",
]
startup_timeout_sec = 30
tool_timeout_sec = 60
[mcp_servers.search-engine-tool.env]
TALORDATA_API_KEY = "your-talordata-api-key"
TALORDATA_BASE_URL = "https://serpapi.talordata.net/serp/v1/request"
SEARXNG_BASE_URL = "http://127.0.0.1:8080"
YDC_API_KEY = "your-you-api-key"
TAVILY_API_KEY = "tvly-your-tavily-api-key"
```
重启Codex，然后运行`codex mcp list`或在Codex会话中使用`/mcp`验证连接。请参阅[官方Codex MCP文档](https://developers.openai.com/codex/mcp/)获取配置选项。
## 用法
### 可用工具
MCP服务器暴露了两个工具：
#### 1. 网页搜索
搜索网页信息。
**参数：**
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `query` | 字符串 | ✅ | - | 搜索查询字符串 |
| `provider` | 字符串 | ❌ | `"auto"` | 要使用的提供商：`"auto"`，`"searxng"`，`"talordata"`，`"you"`或`"tavily"` |
| `max_results` | 整数 | ❌ | `5` | 最大结果数（1-20） |
| `search_depth` | 字符串 | ❌ | `"basic"` | 搜索深度：`"basic"`或`"advanced"`（仅限Tavily） |
| `include_answer` | 布尔值 | ❌ | `false` | 包括AI生成的答案（仅限Tavily和TalorData） |
**响应：**
```json
{
"query": "search query",
"provider": "jina",
"count": 5,
"results": [
{
"href": "https://example.com",
"title": "Result Title",
"abstract": "Result snippet..."
}
]
}
```
#### 2. 网页提取
从特定URL提取内容。
**参数：**
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `url` | 字符串 | ✅ | - | 要提取内容的URL |
| `provider` | 字符串 | ❌ | `"auto"` | 要使用的提供商：`"auto"`，`"local"`或`"tavily"` |
**提供商选项：**
- **`local`**（默认免费提供商）：免费本地提取，无需API密钥。使用trafilatura + BeautifulSoup进行内容提取。
- ⚠️ **限制：**
- 不执行JavaScript
- 无法绕过登录墙、付费墙或CAPTCHA
- 动态/SPA样式页面可能提取不完整
- 超时：20秒（默认）
- **`tavily`**（增强提供商）：Tavily API提取，需要`TAVILY_API_KEY`。
- ✅ **更好**：适用于复杂/动态页面
- ✅ **可以处理**：更具挑战性的站点
- **`auto`**（默认）：首先尝试本地提取，如果失败且`TAVILY_API_KEY`可用，则回退到Tavily。
**响应：**
```json
{
"url": "https://example.com",
"content": "Extracted content...",
"provider": "local"
}
```
### 提供商选择逻辑
- `provider="searxng"`：始终使用SearXNG（需要`SEARXNG_BASE_URL`）
- ⚠️ **限制：**
- 需要自托管SearXNG实例
- 超时：15秒
- 如果返回空结果 → 抛出错误
- `provider="you"`：始终使用You.com（需要`YDC_API_KEY`）
- `provider="tavily"`：始终使用Tavily（需要`TAVILY_API_KEY`）
- `provider="auto"`**（默认）：**
- 初始选择顺序：TalorData → SearXNG → You.com → Tavily
- 发生故障或结果为空时，按当前提供商的备用链进行切换
- 如果未配置提供商 → 抛出错误
## TalorData SERP API
TalorData是一家SERP（搜索引擎结果页面）API提供商，提供来自Google、Bing等搜索引擎的结构化搜索结果。**重要：TalorData仅用于网页搜索，不用于网页提取。**
### 功能
- ✅ **高质量**：顶级SERP API提供商
- ✅ **多引擎支持**：Google、Bing、DuckDuckGo等
- ✅ **结构化输出**：干净的JSON格式，包含详细元数据
- ✅ **AI概述**：支持AI生成的答案（`include_answer`参数）
- ✅ **可选字段**：返回位置、来源、显示链接以进行高级分析
- ✅ **快速响应**：平均响应时间小于1秒
- ✅ **按成功付费**：仅为成功请求付费
- ⚠️ **需要API密钥**：需要`TALORDATA_API_KEY`
- ⚠️ **仅限网页搜索**：不支持网页提取
### 获取API密钥
1. 访问[TalorData仪表盘](https://dashboard.talordata.com)
2. 注册一个免费账户
3. 导航到API游戏场以获取您的API令牌
4. 设置环境变量：
```bash
export TALORDATA_API_KEY="your-api-key-here"
```
### 使用示例
```python
# 使用TalorData进行网页搜索
results = await web_search(
query="OpenAI",
provider="talordata",
max_results=10,
include_answer=True # 获取AI生成的概述
)
# 响应包括：
# - href：结果的URL
# - title：结果的标题
# - abstract：描述或摘要
# - position：搜索结果中的位置（可选）
# - source：源名称（可选）
# - display_link：显示的链接（可选）
# - answer：AI生成的概述（如果include_answer=True）
```
## SearXNG设置
SearXNG是一个免费、自托管的元搜索引擎，它聚合了多个搜索引擎的结果。
### 安装
1. **使用Docker（推荐）**：
```bash
docker run -d --name searxng -p 8080:8080 searxng/searxng:latest
```
2. **手动安装**：请遵循[SearXNG文档](https://github.com/searxng/searxng)
### 配置
设置SearXNG后，请设置环境变量：
```bash
export SEARXNG_BASE_URL="http://127.0.0.1:8080"
```
### 功能
- ✅ **免费**：无需API密钥
- ✅ **注重隐私**：无跟踪
- ✅ **多引擎**：聚合Google、Bing、DuckDuckGo等结果
- ✅ **可定制**：使用`engines`参数选择特定引擎
- ⚠️ **自托管**：需要运行自己的实例
- ⚠️ **超时**：15秒限制以防止MCP挂起
## 开发
### 设置开发环境
```bash
# 克隆仓库
git clone https://github.com/YiHarvest/search-engine-tool.git
cd search-engine-tool
# 使用uv（推荐）
uv sync --all-extras
# 或使用pip
python -m venv .venv
source .venv/bin/activate # 在Windows上：.venv\Scripts\activate
pip install -e ".[dev]"
```
### 运行测试
```bash
# 使用uv
uv run pytest
# 或直接使用pytest
pytest
```
### 构建软件包
```bash
# 使用uv（推荐）
uv build
# 或直接使用build
python -m build
```
### 检查软件包
```bash
# 使用uv
uv run twine check dist/*
# 或直接使用twine
twine check dist/*
```
## API参考
### Jina提供商
- **搜索API**：`https://api.jina.ai/search`
- **阅读器API**：`https://r.jina.ai/{url}`
- **要求**：无需API密钥
- **速率限制**：受Jina公共API限制
### Tavily提供商
- **搜索API**：`https://api.tavily.com/search`
- **提取API**：`https://api.tavily.com/extract`
- **要求**：需要API密钥（`TAVILY_API_KEY`）
- **功能**：高级搜索深度、AI生成的答案
## 项目结构
```
search-engine-tool/
├── src/search_engine_tool_mcp/
│ ├── __init__.py
│ ├── server.py # MCP服务器实现
│ ├── search.py # 网页搜索功能
│ ├── extract.py # 内容提取
│ ├── schemas.py # Pydantic数据模型
│ └── providers/
│ ├── __init__.py
│ ├── you.py # You.com提供商（搜索）
│ ├── tavily.py # Tavily提供商（搜索+提取）
│ └── local_extract.py # 本地提取提供商（免费）
├── tests/
│ ├── test_search.py
│ └── test_providers.py
│ └── test_extract.py
├── pyproject.toml
└── README.md
## 许可证
MIT 许可证
## 贡献
欢迎贡献！请随意提交拉取请求。
## 支持
对于问题和功能请求，请使用 [GitHub Issues](https://github.com/YiHarvest/search-engine-tool-mcp/issues) 页面。
