内容
# SerpMCP
<!-- mcp-name: io.github.AceDataCloud/mcp-serp -->
[](https://pypi.org/project/mcp-serp/)
[](https://pypi.org/project/mcp-serp/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
AceDataCloud 平台的谷歌搜索服务器，通过 AceDataCloud API 使用 SERP API。
在 Claude、VS Code 或任何支持 MCP 的客户端中执行谷歌搜索并获取结构化结果。
## 功能
- **网页搜索** - 常规的谷歌网页搜索，返回结构化结果
- **图片搜索** - 搜索图片，返回图片网址和缩略图
- **新闻搜索** - 获取最新的新闻文章
- **视频搜索** - 查找 YouTube 和其他来源的视频
- **地点搜索** - 搜索本地企业和地点
- **地图搜索** - 查找地点和地理信息
- **知识图谱** - 获取结构化的实体信息
- **本地化** - 支持多个国家和语言
- **时间筛选** - 按时间范围筛选结果
## 工具参考
| 工具 | 描述 |
|------|-------------|
| `serp_google_search` | 使用 SERP API 搜索谷歌并获取结构化结果。 |
| `serp_google_images` | 搜索谷歌图片并获取图片结果。 |
| `serp_google_news` | 搜索谷歌新闻并获取新闻文章结果。 |
| `serp_google_videos` | 搜索谷歌视频并获取视频结果。 |
| `serp_google_places` | 搜索谷歌本地地点和企业。 |
| `serp_google_maps` | 搜索谷歌地图中的地点。 |
| `serp_list_search_types` | 列出所有可用的谷歌搜索类型。 |
| `serp_list_countries` | 列出常用的国家代码用于谷歌搜索。 |
| `serp_list_languages` | 列出常用的语言代码用于谷歌搜索。 |
| `serp_list_time_ranges` | 列出可用的谷歌搜索时间范围筛选选项。 |
| `serp_get_usage_guide` | 获取谷歌 SERP 工具的综合使用指南。 |
## 快速开始
### 1. 获取 API Token
1. 在 [AceDataCloud 平台](https://platform.acedata.cloud) 注册
2. 进入 [API 文档页面](https://platform.acedata.cloud/documents/44c86226-8eaa-49bf-85f3-1fae8d2e23f1)
3. 点击 **"获取"** 获取您的 API token
4. 复制 token 备用
### 2. 使用托管服务器（推荐）
AceDataCloud 托管了一个受管理的 MCP 服务器 - **无需本地安装**。
**端点：** `https://serp.mcp.acedata.cloud/mcp`
所有请求都需要 Bearer token。使用步骤 1 中的 API token。
#### Claude.ai
直接在 [Claude.ai](https://claude.ai) 上使用 OAuth 连接 - **无需 API token**：
1. 进入 Claude.ai **设置 → 集成 → 添加更多**
2. 输入服务器网址：`https://serp.mcp.acedata.cloud/mcp`
3. 完成 OAuth 登录流程
4. 在对话中开始使用工具
#### Claude Desktop
添加到您的配置（`~/Library/Application Support/Claude/claude_desktop_config.json` 在 macOS 上）：
```json
{
"mcpServers": {
"serp": {
"type": "streamable-http",
"url": "https://serp.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
#### Cursor / Windsurf
添加到您的 MCP 配置（`.cursor/mcp.json` 或 `.windsurf/mcp.json`）：
```json
{
"mcpServers": {
"serp": {
"type": "streamable-http",
"url": "https://serp.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
#### VS Code (Copilot)
添加到您的 VS Code MCP 配置（`.vscode/mcp.json`）：
```json
{
"servers": {
"serp": {
"type": "streamable-http",
"url": "https://serp.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
或安装 [Ace Data Cloud MCP 扩展](https://marketplace.visualstudio.com/items?itemName=acedatacloud.acedatacloud-mcp) 用于 VS Code，它通过一键设置注册托管的 MCP 服务器。
#### JetBrains IDEs
1. 进入 **设置 → 工具 → AI 助手 → 模型上下文协议（MCP）**
2. 点击 **添加** → **HTTP**
3. 粘贴：
```json
{
"mcpServers": {
"serp": {
"url": "https://serp.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
#### Claude Code
Claude Code 原生支持 MCP 服务器：
```bash
claude mcp add serp --transport http https://serp.mcp.acedata.cloud/mcp \
-h "Authorization: Bearer YOUR_API_TOKEN"
```
或添加到您的项目的 `.mcp.json`：
```json
{
"mcpServers": {
"serp": {
"type": "streamable-http",
"url": "https://serp.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
#### Cline
添加到 Cline 的 MCP 设置（`.cline/mcp_settings.json`）：
```json
{
"mcpServers": {
"serp": {
"type": "streamable-http",
"url": "https://serp.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
#### Amazon Q Developer
添加到您的 MCP 配置：
```json
{
"mcpServers": {
"serp": {
"type": "streamable-http",
"url": "https://serp.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
#### Roo Code
添加到 Roo Code MCP 设置：
```json
{
"mcpServers": {
"serp": {
"type": "streamable-http",
"url": "https://serp.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
#### Continue.dev
添加到 `.continue/config.yaml`：
```yaml
mcpServers:
- name: serp
type: streamable-http
url: https://serp.mcp.acedata.cloud/mcp
headers:
Authorization: "Bearer YOUR_API_TOKEN"
```
#### Zed
添加到 Zed 的设置（`~/.config/zed/settings.json`）：
```json
{
"language_models": {
"mcp_servers": {
"serp": {
"url": "https://serp.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
}
```
#### cURL 测试
```bash
# 健康检查（无需认证）
curl https://serp.mcp.acedata.cloud/health
# MCP 初始化
curl -X POST https://serp.mcp.acedata.cloud/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```
### 3. 或本地运行（替代方案）
如果您更喜欢在自己的机器上运行服务器：
```bash
# 从 PyPI 安装
pip install mcp-serp
# 或
uvx mcp-serp
# 设置您的 API token
export ACEDATACLOUD_API_TOKEN="your_token_here"
# 运行（stdio 模式适用于 Claude Desktop / 本地客户端）
mcp-serp
# 运行（HTTP 模式适用于远程访问）
mcp-serp --transport http --port 8000
```
#### Claude Desktop（本地）
```json
{
"mcpServers": {
"serp": {
"command": "uvx",
"args": ["mcp-serp"],
"env": {
"ACEDATACLOUD_API_TOKEN": "your_token_here"
}
}
}
}
```
#### Docker（自托管）
```bash
docker pull ghcr.io/acedatacloud/mcp-serp:latest
docker run -p 8000:8000 ghcr.io/acedatacloud/mcp-serp:latest
```
客户端使用自己的 Bearer token 连接 - 服务器从每个请求的 `Authorization` 头中提取 token。
## 可用工具
### 搜索工具
| 工具 | 描述 |
| -------------------- | --------------------------------------- |
| `serp_google_search` | 灵活的谷歌搜索，支持所有选项 |
| `serp_google_images` | 搜索图片 |
| `serp_google_news` | 搜索新闻文章 |
| `serp_google_videos` | 搜索视频 |
| `serp_google_places` | 搜索本地地点/企业 |
| `serp_google_maps` | 搜索地图位置 |
### 信息工具
| 工具 | 描述 |
| ------------------------ | ------------------------------------ |
| `serp_list_search_types` | 列出可用的搜索类型 |
| `serp_list_countries` | 列出国家代码用于本地化 |
| `serp_list_languages` | 列出语言代码用于本地化 |
| `serp_list_time_ranges` | 列出时间范围筛选选项 |
| `serp_get_usage_guide` | 获取综合使用指南 |
## 使用示例
### 基本网页搜索
```
用户：搜索有关人工智能的信息
Claude：我将搜索有关 AI 的信息。
[调用 serp_google_search，查询="人工智能"]
```
### 新闻搜索与时间筛选
```
用户：最新的科技新闻是什么？
Claude：我将搜索最近的科技新闻。
[调用 serp_google_news，查询="科技"，时间范围="qdr:d"]
```
### 本地化搜索
```
用户：查找东京的热门餐厅
Claude：我将搜索东京的餐厅。
[调用 serp_google_places，查询="东京热门餐厅"，国家="jp"]
```
### 图片搜索
```
用户：查找北极光的图片
Claude：我将搜索极光的图片。
[调用 serp_google_images，查询="北极光 极光"]
```
## 搜索参数
### 搜索类型
| 类型 | 描述 |
| -------- | ---------------------------- |
| `search` | 常规网页搜索（默认） |
| `images` | 图片搜索 |
| `news` | 新闻文章 |
| `maps` | 地图结果 |
| `places` | 本地企业 |
| `videos` | 视频结果 |
### 时间范围筛选
| 代码 | 时间范围 |
| ------- | ---------- |
| `qdr:h` | 过去一小时 |
| `qdr:d` | 过去一天 |
| `qdr:w` | 过去一周 |
| `qdr:m` | 过去一个月 |
### 常用国家代码
| 代码 | 国家 |
| ---- | -------------- |
| `us` | 美国 |
| `uk` | 英国 |
| `cn` | 中国 |
| `jp` | 日本 |
| `de` | 德国 |
| `fr` | 法国 |
### 常用语言代码
| 代码 | 语言 |
| ------- | -------------------- |
| `en` | 英语 |
| `zh-cn` | 简体中文 |
| `ja` | 日语 |
| `es` | 西班牙语 |
| `fr` | 法语 |
| `de` | 德语 |
## 响应结构
### 常规搜索结果
- **知识图谱**：实体信息（公司、人物等）
- **答案框**：直接答案
- **有机结果**：常规搜索结果，包含标题、链接、摘要
- **人们也问**：相关问题
- **相关搜索**：相关查询
### 图片搜索结果
- **图片**：图片结果，包含网址和缩略图
### 新闻搜索结果
- **新闻**：新闻文章，包含来源和日期
## 配置
### 环境变量
| 变量 | 描述 | 默认值 |
| --------------------------- | --------------------------- | --------------------------- |
| `ACEDATACLOUD_API_TOKEN` | AceDataCloud API token | **必填** |
| `ACEDATACLOUD_API_BASE_URL` | AceDataCloud API 基本网址 | `https://api.acedata.cloud` |
| `ACEDATACLOUD_OAUTH_CLIENT_ID` | AceDataCloud OAuth 客户端 ID（托管模式） | — |
| `ACEDATACLOUD_PLATFORM_BASE_URL` | AceDataCloud 平台基本网址 | `https://platform.acedata.cloud` |
| `SERP_REQUEST_TIMEOUT` | 请求超时（秒） | `30` |
| `LOG_LEVEL` | 日志级别 | `INFO` |
### 命令行选项
```bash
mcp-serp --help
选项：
--version 显示版本
--transport 传输模式：stdio（默认）或 http
--port HTTP 传输端口（默认：8000）
```
## 开发
### 设置开发环境
```bash
# 克隆仓库
git clone https://github.com/AceDataCloud/SerpMCP.git
cd SerpMCP
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # 或 `.venv\Scripts\activate` 在 Windows 上
# 安装开发依赖项
pip install -e ".[dev,test]"
```
### 运行测试
```bash
# 运行单元测试
pytest
# 运行覆盖率测试
pytest --cov=core --cov=tools
# 运行集成测试（需要 API token）
pytest tests/test_integration.py -m integration
```
### 代码质量
```bash
# 格式化代码
ruff format .
# 检查代码
ruff check .
# 类型检查
mypy core tools
```
### 构建和发布
```bash
# 安装构建依赖项
pip install -e ".[release]"
# 构建软件包
python -m build
# 上传到 PyPI
twine upload dist/*
```
## 项目结构
```
SerpMCP/
├── core/ # 核心模块
│ ├── __init__.py
│ ├── client.py # SERP API 的 HTTP 客户端
│ ├── config.py # 配置管理
│ ├── exceptions.py # 自定义异常
│ └── server.py # MCP 服务器初始化
├── tools/ # MCP 工具定义
│ ├── __init__.py
│ ├── search_tools.py # 搜索工具
│ └── info_tools.py # 信息工具
├── prompts/ # MCP 提示模板
│ └── __init__.py
├── tests/ # 测试套件
│ ├── conftest.py
│ ├── test_client.py
│ └── test_config.py
├── deploy/ # 部署配置
│ └── production/
│ ├── deployment.yaml
│ ├── ingress.yaml
│ └── service.yaml
├── .env.example # 环境模板
├── .gitignore
├── CHANGELOG.md
├── Dockerfile # HTTP 模式的 Docker 镜像
├── docker-compose.yaml # Docker Compose 配置
├── LICENSE
├── main.py # 入口点
├── pyproject.toml # 项目配置
└── README.md
```
## API 参考
此服务器封装了 [AceDataCloud 谷歌 SERP API](https://platform.acedata.cloud/documents/44c86226-8eaa-49bf-85f3-1fae8d2e23f1）：
- [谷歌 SERP API 文档](https://platform.acedata.cloud/documents/44c86226-8eaa-49bf-85f3-1fae8d2e23f1)
## 贡献
欢迎贡献！请：
1. Fork 仓库
2. 创建功能分支（`git checkout -b feature/amazing`）
3. 提交更改（`git commit -m 'Add amazing feature'`）
4. 推送到分支（`git push origin feature/amazing`）
5. 开启 Pull Request
## 许可证
MIT 许可证 - 请参阅 [LICENSE](LICENSE) 获取详细信息。
## 链接
- [AceDataCloud 平台](https://platform.acedata.cloud)
- [谷歌 SERP API](https://platform.acedata.cloud/documents/44c86226-8eaa-49bf-85f3-1fae8d2e23f1)
- [模型上下文协议](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
---
由 [AceDataCloud](https://platform.acedata.cloud) 制作
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器