内容
# serper-dev-mcp
本地的 [模型上下文协议](https://modelcontextprotocol.io/) 服务器，用于 [Serper.dev](https://serper.dev/) 的 Google 搜索和网页抓取 API。它为 [Claude Code](https://www.anthropic.com/claude) 和 [Codex](https://www.developers.codex) 等客户端提供了十二种工具。
服务器需要 Node.js 20 或更高版本，以及 Serper.dev API 密钥。每个请求都会根据 Serper 当前的定价，从配置的 Serper 账户中消耗积分。
## 工具列表
| MCP 工具 | Serper 端点 | 用途 | 必需参数 |
| --- | --- | --- | --- |
| `serper_search` | `search` | Google 网页结果 | `q` |
| `serper_images` | `images` | Google 图片结果 | `q` |
| `serper_videos` | `videos` | Google 视频结果 | `q` |
| `serper_places` | `places` | Google 本地地点结果 | `q` |
| `serper_maps` | `maps` | Google 地图地点结果 | 至少一个 `q`、`placeId` 或 `cid` |
| `serper_reviews` | `reviews` | Google 地点评论 | 至少一个 `cid`、`fid` 或 `placeId` |
| `serper_news` | `news` | Google 新闻结果 | `q` |
| `serper_shopping` | `shopping` | Google 购物结果 | `q` |
| `serper_lens` | `lens` | Google Lens 图片分析 | `url` |
| `serper_patents` | `patents` | Google 专利结果 | `q` |
| `serper_autocomplete` | `autocomplete` | Google 查询建议 | `q` |
| `serper_scrape` | `scrape` | 从网页中提取内容 | `url` |
### 参数
类似搜索的工具接受以下参数：
- `q`（字符串）：查询文本。
- `location`（字符串，可选）：地理位置，用于本地化结果。
- `gl`（字符串，可选）：两位小写国家/地区代码，例如 `us` 或 `tr`。
- `hl`（字符串，可选）：两位小写界面语言代码，例如 `en` 或 `tr`。
- `tbs`（字符串，可选）：Google 基于时间的过滤器，例如 `qdr:h` 或 `qdr:m`。
- `num`（正整数，可选）：请求的最多结果数。
- `page`（正整数，可选）：基于 1 的结果页。
`serper_search`、`serper_images`、`serper_videos`、`serper_places`、`serper_news`、`serper_shopping` 和 `serper_patents` 接受所有七个类似搜索的参数。`serper_autocomplete` 接受 `q`、`location`、`gl` 和 `hl`。
专用工具使用这些参数：
- `serper_maps`：可选 `q`、`hl`、`ll`、`placeId`、`cid` 和 `page`。至少需要 `q`、`placeId` 或 `cid` 之一。`ll` 标识 Serper 接受的地图中心/缩放字符串。
- `serper_reviews`：可选 `cid`、`fid`、`placeId`、`gl`、`hl`、`sortBy`、`topicId` 和 `nextPageToken`。至少需要一个地点标识符。`sortBy` 是 `mostRelevant`、`newest`、`highestRating` 或 `lowestRating` 之一。
- `serper_lens`：需要 `url`，还可选 `location`、`gl`、`hl` 和 `tbs`。
- `serper_scrape`：需要 `url`，还可选布尔值 `includeMarkdown`。
Lens 和 scrape URL 必须使用 `http` 或 `https`。每次成功的调用都返回完整的 Serper 对象作为 MCP `structuredContent`，以及为不支持结构化输出的客户端提供的格式化 JSON 文本。
## 使用 npx 运行
该软件包设计为由 MCP 客户端启动，但在 `SERPER_API_KEY` 已在进程环境中设置时，可以直接启动：
```bash
SERPER_API_KEY=YOUR_KEY npx -y serper-dev-mcp
```
进程使用 MCP JSON-RPC 在 stdout 上进行通信，因此它不会打印启动横幅。
## Claude Code
为当前用户注册：
```bash
claude mcp add --scope user serper-dev -e SERPER_API_KEY=YOUR_KEY -- npx -y serper-dev-mcp
```
仅当项目范围配置合适时，请使用 `--scope project` 代替 `--scope user`。不要在共享的 MCP 配置中提交实际密钥。
## Codex
在 Codex 中注册服务器：
```bash
codex mcp add serper-dev --env SERPER_API_KEY=YOUR_KEY -- npx -y serper-dev-mcp
```
将实际值保存在适合您计算机的环境或机密管理工作流中，而不是存储在存储库文件中。
## 本地开发
从源代码安装和构建：
```bash
git clone https://github.com/GreXLin85/serper.dev-mcp.git
cd serper.dev-mcp
npm install
npm run build
SERPER_API_KEY=YOUR_KEY node dist/index.js
```
离线项目检查：
```bash
npm test
npm run typecheck
npm run build
npm pack --dry-run
```
测试注入伪造的 HTTP 响应，不会消耗 Serper 积分。对于交互式协议检查，请构建软件包并通过 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 启动 `node dist/index.js`，仅通过其环境配置提供 `SERPER_API_KEY`。
## 安全
- API 密钥仅从 `SERPER_API_KEY` 读取，绝不会作为工具参数。
- 服务器不会记录请求头、主体、成功响应或 API 密钥。
- HTTP 响应详细信息有边界，反映的凭证在错误跨越 MCP 边界之前会被编辑。
- 网络、超时、无效响应和意外错误使用安全的消息，不包含堆栈跟踪。
- 只有 `http` 和 `https` URL 被 Lens 和 scrape 工具接受。
- `.env` 文件和本地 `requests` 参考文件被排除在 Git 和 npm 软件包之外。
在发布或共享存储库之前，请撤销和轮换已粘贴到命令、文档、问题、聊天或其他非机密存储中的任何凭证。
## 发布检查清单
在发布版本之前：
1.撤销任何先前公开的密钥，并确认跟踪的文件或 Git 历史记录中不存在凭证。
2. 在 Node.js 20 或更高版本上运行 `npm test`、`npm run typecheck` 和 `npm run build`。
3. 运行 `npm pack --dry-run`，并确认软件包仅包含编译的 `dist` 输出、`README.md`、`LICENSE` 和 npm 生成的软件包元数据。
4. 使用具有有限积分的非生产密钥，通过 MCP Inspector 检查十二种公开的工具。
5. 更新版本和发布说明，然后使用预期的 npm 账户和出处设置发布。
6. 标记确切的发布提交，并创建匹配的 GitHub 发布。
发布、远程创建、CI 设置和实时 API 烟雾测试并未被此存储库自动执行。
## 致谢和许可
本项目使用官方的 [模型上下文协议 TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)，并与 [Serper.dev](https://serper.dev/) 集成。它与 Google 或 Serper.dev 无关。
在 [MIT License](LICENSE) 下许可。版权所有 2026 GreXLin85。
