内容
# DDGS MCP 服务器
一款封装了 [DDGS（Dux 分布式全局搜索）](https://github.com/deedy5/ddgs) 库的模型上下文协议（MCP）服务器，为 AI 代理提供跨多个搜索引擎的强大网络搜索能力。
> **注意：** 整个代码库由 Claude Sonnet 4.5 生成。仓库所有者不对使用该软件可能出现的任何问题、错误或情况负责。请自担风险。
## 功能
### 搜索类型
- **文本搜索**：跨 Bing、Brave、DuckDuckGo、Google、Mojeek、Yahoo、维基百科等搜索引擎进行网络搜索
- **图像搜索**：搜索图像，支持大小、颜色、类型、布局和许可证过滤
- **视频搜索**：查找视频，支持分辨率、时长和许可证过滤
- **新闻搜索**：从多个来源搜索新闻文章
- **图书搜索**：跨 Anna's Archive 搜索图书
### 高级功能
- **多搜索引擎**：在后端之间自动切换以提高可靠性
- **搜索运算符**：支持 filetype:、site:、intitle:、inurl: 和布尔运算符
- **区域搜索**：支持国家-语言组合（例如 us-en、uk-en、cn-zh）
- **代理支持**：支持 HTTP/HTTPS/SOCKS5 代理，包括 Tor 浏览器集成
- **灵活过滤**：支持 Safesearch、时间限制和内容特定过滤
## 安装
### 先决条件
- Python 3.9 或更高版本
- pip
### 设置
1. **克隆或导航到仓库**：
```powershell
cd "d:\MCP Servers\ddgs-mcp-wrapper"
```
2. **创建虚拟环境**（推荐）：
```powershell
python -m venv venv
.\venv\Scripts\Activate.ps1
```
3. **安装依赖项**：
```powershell
pip install -r requirements.txt
```
或直接安装：
```powershell
pip install mcp ddgs pydantic
```
## 使用
### 运行服务器
#### 独立运行
```powershell
python server.py
```
#### 使用 MCP 客户端配置
添加到您的 MCP 客户端配置中（例如 Claude Desktop、Cline 等）：
**适用于 Claude Desktop** (`%APPDATA%\Claude\claude_desktop_config.json`)：
```json
{
"mcpServers": {
"ddgs-search": {
"command": "python",
"args": ["d:\\MCP Servers\\ddgs-mcp-wrapper\\server.py"],
"env": {
"DDGS_PROXY": ""
}
}
}
}
```
**适用于 Cline** (`.vscode/settings.json`)：
```json
{
"mcp.servers": {
"ddgs-search": {
"command": "python",
"args": ["d:\\MCP Servers\\ddgs-mcp-wrapper\\server.py"]
}
}
}
```
### 使用 UV（替代方案）
如果您更喜欢使用 `uv`：
```powershell
uvx --from mcp ddgs-mcp-server
```
## 可用工具
### 1. ddgs_text_search
搜索网络中的文本内容。
**参数**：
- `query`（必填）：搜索查询，可选运算符
- `region`：区域代码（默认："us-en"）
- `safesearch`："on"、"moderate" 或 "off"（默认："moderate"）
- `timelimit`："d"（天）、"w"（周）、"m"（月）、"y"（年）
- `max_results`：最大结果数（1-100，默认：10）
- `backend`："auto" 或逗号分隔的后端（默认："auto"）
- `proxy`：代理 URL 或 "tb" 表示 Tor 浏览器
**示例**：
```json
{
"query": "python machine learning filetype:pdf",
"region": "us-en",
"max_results": 20,
"timelimit": "y"
}
```
### 2. ddgs_image_search
搜索图像并应用过滤器。
**参数**：
- `query`（必填）：图像搜索查询
- `region`、`safesearch`、`timelimit`、`max_results`：与文本搜索相同
- `size`："Small"、"Medium"、"Large"、"Wallpaper"
- `color`："color"、"Monochrome"、"Red"、"Orange"、"Yellow"、"Green"、"Blue" 等
- `type_image`："photo"、"clipart"、"gif"、"transparent"、"line"
- `layout`："Square"、"Tall"、"Wide"
- `license_image`："any"、"Public"、"Share"、"ShareCommercially"、"Modify"、"ModifyCommercially"
### 3. ddgs_video_search
搜索视频。
**参数**：
- `query`（必填）：视频搜索查询
- `region`、`safesearch`、`timelimit`、`max_results`：与文本搜索相同
- `resolution`："high" 或 "standard"
- `duration`："short"、"medium"、"long"
- `license_videos`："creativeCommon"、"youtube"
### 4. ddgs_news_search
搜索新闻文章。
**参数**：
- `query`（必填）：新闻搜索查询
- `region`、`safesearch`、`timelimit`、`max_results`：与文本搜索相同
- `backend`："auto"、"bing"、"duckduckgo"、"yahoo"
### 5. ddgs_book_search
搜索图书。
**参数**：
- `query`（必填）：图书搜索查询（标题、作者、ISBN）
- `max_results`：最大结果数（1-100，默认：10）
## 搜索运算符
文本搜索支持高级运算符：
| 运算符 | 描述 |
|----------|-------------|
| `cats dogs` | 包含关于猫或狗的结果 |
| `"exact phrase"` | 短语的精确匹配 |
| `cats -dogs` | 减少结果中关于狗的内容 |
| `cats +dogs` | 增加结果中关于狗的内容 |
| `filetype:pdf` | 特定文件类型（pdf、doc、xls、ppt、html） |
| `site:example.com` | 来自特定域名的结果 |
| `-site:example.com` | 排除特定域名 |
| `intitle:keyword` | 页面标题中包含关键词 |
| `inurl:keyword` | URL 中包含关键词 |
## 代理配置
### 使用 Tor 浏览器
```json
{
"proxy": "tb"
}
```
或设置环境变量：
```powershell
$env:DDGS_PROXY = "socks5h://127.0.0.1:9150"
```
### 使用自定义代理
```json
{
"proxy": "http://user:pass@proxy.example.com:8080"
}
```
支持的协议：`http://`、`https://`、`socks5://`、`socks5h://`
## 开发
### 项目结构
```
ddgs-mcp-wrapper/
├── server.py # 主要的 MCP 服务器实现
├── pyproject.toml # 项目配置
├── requirements.txt # Python 依赖项
├── README.md # 本文件
└── .gitignore # Git 忽略规则
```
### 测试服务器
使用 MCP 客户端或 MCP 检查器进行测试：
```powershell
npm install -g @modelcontextprotocol/inspector
mcp-inspector python server.py
```
### 调试
通过修改 `server.py` 启用调试日志：
```python
logging.basicConfig(level=logging.DEBUG)
```
## AI 代理提示
1. **使用 `backend='auto'`**：自动处理后端暂时不可用
2. **指定区域**：使用区域代码（如 `ar-es`、`pl-pl`、`cn-zh`）提高搜索质量
3. **分页查询**：单次查询返回第 1 页的结果；可迭代查询获取更多结果
4. **使用搜索运算符**：组合运算符获取精确结果（例如 `"machine learning" filetype:pdf site:.edu`）
5. **区域限制的代理**：如果后端在您的国家/地区被限速或阻止，请使用代理或 Tor 浏览器
## 故障排除
### 常见问题
**"模块未找到" 错误**：
```powershell
pip install --upgrade mcp ddgs pydantic
```
**限速**：
- 使用 `backend='auto'` 在引擎之间切换
- 增加请求之间的延迟
- 使用代理或 Tor 浏览器
**导入错误**：
```powershell
# 验证安装
pip list | Select-String -Pattern "mcp|ddgs|pydantic"
```
**连接超时**：
- 增加 `get_ddgs_instance()` 调用中的超时时间
- 检查代理配置
- 尝试不同的后端
## 许可证
MIT 许可证 - 您可以随意在您的项目中使用。
## 贡献
欢迎贡献！请：
1. Fork 仓库
2. 创建功能分支
3. 提交拉取请求
## 资源
- [MCP 文档](https://modelcontextprotocol.io/)
- [DDGS 库](https://github.com/deedy5/ddgs)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
## 免责声明
**代码生成：** 本项目完全由 Claude Sonnet 4.5 AI 生成。仓库所有者不对使用此软件可能出现的任何问题、错误或后果负责。
**使用：** 本服务器仅用于教育和研究目的。请尊重搜索引擎的服务条款和速率限制。请自担风险。
