内容
<div align="center">
<img src="./assets/serphouse-logo.png" alt="SERPHouse logo" width="80" />
# SERPHouse MCP 服务器
**连接 AI 助手到实时 SERP 数据、谷歌垂直搜索和 SEO 情报 — 由 [SERPHouse](https://serphouse.com) 提供支持。**
在 Cursor、VS Code、Claude Desktop 或任何支持 MCP 的客户端中直接运行谷歌、Bing 和 Yahoo 搜索，解析位置，并查询工作、本地、视频等 — 无需自定义 API 集成。
<br />
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
[](https://insiders.vscode.dev/redirect/mcp/install?name=serphouse-mcp&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.serphouse.com%2Fmcp%22%2C%22headers%22%3A%7B%22SERPHOUSE_API%22%3A%22YOUR_SERPHouse_API_KEY%22%7D%7D)
[](cursor://anysphere.cursor-deeplink/mcp/install?name=serphouse-mcp&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLnNlcnBob3VzZS5jb20vbWNwIiwiaGVaZGVycyI6eyJTRVJQSE9VU0VfQVBJIjoiWU9VUl9TRVJQSG91c2VfQVBJX0tFWSJ9fQ==)
[](https://serphouse.com)
[](https://github.com/SERPHouse)
[](https://linkedin.com/company/serphouse)
</div>
---
## 目录
- [为什么选择 SERPHouse MCP](#为什么选择-serphouse-mcp)
- [快速开始（托管）](#快速开始托管)
- [您可以询问的内容](#您可以询问的内容)
- [工具概述](#工具概述)
- [本地自托管](#本地自托管)
- [使用 Docker 自托管](#使用-docker自托管)
- [与本地 Llama 模型（Ollama）一起使用](#与本地-llama模型ollama一起使用)
- [故障排除](#故障排除)
- [贡献](#贡献)
- [许可证](#许可证)
---
## 为什么选择 SERPHouse MCP
| | |
|---|---|
| **21 个 MCP 工具** | 实时谷歌、Bing 和 Yahoo SERP，谷歌垂直搜索和账户查询 — 所有这些都通过类型化的模式公开 |
| **零胶水代码** | 您的助手选择合适的工具；您用自然语言描述您需要的内容 |
| **托管或自托管** | 使用托管的端点 `https://mcp.serphouse.com/mcp`，或在您自己的基础设施上运行服务器 |
| **内置上下文** | MCP 资源（`serphouse_capabilities`、`serphouse_constraints`、`serphouse_examples`）自动教导 AI 使用规则 |
---
## 快速开始（托管）
最快的路径 — 无需构建步骤，无需维护服务器。
**1.** 从 [SERPHouse 仪表盘](https://www.serphouse.com) 获取您的 API 密钥。
**2.** 将服务器添加到您的 MCP 客户端配置：
```json
{
"mcpServers": {
"serphouse": {
"url": "https://mcp.serphouse.com/mcp",
"headers": {
"SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
}
}
}
}
```
**3.** 开始聊天。要求您的助手搜索谷歌、Bing 或 Yahoo，查找位置，获取工作或检查您的账户 — 它将路由到正确的工具。
> **一键安装：** 使用上面的 **在 VS Code 中安装** 或 **在 Cursor 中安装** 徽章，然后用您的替换占位符 API 密钥。
---
## 您可以询问的内容
适用于需要实时搜索数据的 SEO 团队、机构和 SaaS 市场营销人员 — 无需仪表盘、脚本或上下文切换。
| 为什么使用它 | 示例提示 |
|----------------|----------------|
| **跟踪您的排名** | *"我们在谷歌美国桌面版中排名多少位，关键词是 'crm software' ？"* |
| **超越竞争对手** | *"谁拥有伦敦 '项目管理软件' 的前 5 名位置？"* |
| **拥有本地搜索** | *"芝加哥 '紧急水管工' 的谷歌本地结果。"* |
| **发现关键词** | *"谷歌自动填充建议 'best saas for' 什么？"* |
| **监控位置** | *"在纽约市运行一个移动版 Bing SERP 检查，查看我们的品牌排名。"* |
| **多引擎覆盖** | *"比较雅虎和谷歌关于 '电动汽车' 的新闻结果。"* |
---
## 工具概述
服务器公开了 **21 个工具**，分为五个类别。谷歌和 Bing SERP 请求需要一个位置字段 — `loc`（例如 `Austin,Texas,United States`）或 `loc_id`（来自 `serphouse_location_search`）。切勿在这些端点上发送两者或省略两者。雅虎 SERP 工具不需要位置。
### 参考
| 工具 | 描述 |
|------|-------------|
| `serphouse_domain_list` | 支持的谷歌、Bing 和雅虎搜索域 |
| `serphouse_language_list` | 按搜索引擎类型划分的语言代码 |
| `serphouse_location_search` | 将城市/国家名称解析为 `loc_id` |
| `serphouse_account_info` | 账户余额和使用情况 |
### 谷歌 SERP
| 工具 | 描述 |
|------|-------------|
| `serphouse_google_web` | 谷歌网页搜索 |
| `serphouse_google_image` | 谷歌图片搜索 |
| `serphouse_google_news` | 谷歌新闻搜索 |
| `serphouse_google_shop` | 谷歌购物搜索 |
| `serphouse_serp_google_advanced` | 高级谷歌 SERP，带有扩展参数（最多 100 个结果） |
### Bing SERP
| 工具 | 描述 |
|------|-------------|
| `serphouse_bing_web` | Bing 网页搜索 |
| `serphouse_bing_image` | Bing 图片搜索 |
| `serphouse_bing_news` | Bing 新闻搜索 |
### 雅虎 SERP
| 工具 | 描述 |
|------|-------------|
| `serphouse_yahoo_web` | 雅虎网页搜索 |
| `serphouse_yahoo_image` | 雅虎图片搜索 |
| `serphouse_yahoo_news` | 雅虎新闻搜索 |
### 谷歌垂直搜索
| 工具 | 描述 |
|------|-------------|
| `serphouse_google_jobs` | 谷歌工作搜索 |
| `serphouse_google_autocomplete` | 谷歌自动填充建议 |
| `serphouse_google_videos` | 谷歌视频结果 |
| `serphouse_google_short_videos` | 谷歌短视频（Shorts） |
| `serphouse_google_forums` | 谷歌论坛结果 |
| `serphouse_google_local` | 谷歌本地/地图结果 |
---
## 本地自托管
在您的机器上运行服务器以获得完全控制或本地开发。
```bash
git clone https://github.com/SERPHouse/serphouse-mcp.git
cd serphouse-mcp
npm install
npm run build
npm start
```
服务器监听 `http://localhost:3000`。MCP 端点：`POST /mcp`
将您的 MCP 客户端指向本地实例：
```json
{
"mcpServers": {
"serphouse": {
"url": "http://localhost:3000/mcp",
"headers": {
"SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
}
}
}
}
```
### 命令
| 命令 | 描述 |
|---------|-------------|
| `npm run build` | 编译 TypeScript 到 `dist/` |
| `npm start` | 运行 HTTP 服务器 (`http://localhost:3000/mcp`) |
| `npm run start:stdio` | 运行_stdio传输服务器（本地 MCP 进程模式） |
| `npm run dev` | 运行带有热重载的 HTTP 服务器 |
| `npm run dev:ins` | 启动 MCP 检查器以调试_stdio服务器 |
| `npm run typecheck` | 类型检查，无需发出文件 |
健康检查：`GET http://localhost:3000/health`
### 服务器选项
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `PORT` | `3000` | HTTP 监听端口 |
| `HOST` | `0.0.0.0` | HTTP 绑定地址 |
身份验证仅限头部。发送 `SERPHOUSE_API: <api_key>` 在每个 `/mcp` 请求上（在您的 MCP 客户端头部中配置）。
---
## 使用 Docker 自托管
在 Docker 中本地运行 MCP 服务器，无需安装 Node.js。
```bash
docker compose up -d
```
服务器运行在 `http://localhost:3000/mcp`。
使用头部中的 API 密钥连接您的 MCP 客户端：
```json
{
"mcpServers": {
"serphouse": {
"url": "http://localhost:3000/mcp",
"headers": {
"SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
}
}
}
}
```
---
## 与本地 Llama 模型（Ollama）一起使用
使用 [`ollmcp`](https://github.com/jonigl/mcp-client-for-ollama) 将您的 SERPHouse MCP 服务器连接到本地 Llama 模型（例如 Llama 3.1 或 3.2）— 一个交互式终端 UI 客户端，将实时搜索引擎功能直接带到您的本地 LLM 工作流中。
### 先决条件
| 要求 | 备注 |
|-------------|-------|
| **支持工具调用的 Llama 模型** | 支持工具调用的模型（例如 `llama3.1`、`llama3.2`）通过 [Ollama](https://ollama.com) 安装并运行 |
| **Python 3.10+** | 运行 `ollmcp` 终端客户端所需 |
| **Node.js** | 通过 `npx` 运行 SERPHouse MCP 服务器所需 |
### 1. 安装 `ollmcp`
`ollmcp` 是 Python 客户端，因此使用 `pip` 全局安装：
```bash
pip install --upgrade ollmcp
```
### 2. 创建 `config.json` 文件
客户端需要一个配置文件，告诉它如何启动 SERPHouse 服务器并传递您的 API 凭证。在工作文件夹中创建一个 `config.json`：
```json
{
"mcpServers": {
"serphouse-mcp": {
"url": "https://mcp.serphouse.com/mcp",
"headers": {
"SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
}
}
}
}
```
> 将 `YOUR_SERPHouse_API_KEY` 替换为 [SERPHouse 仪表盘](https://www.serphouse.com) 中的有效密钥。
### 3. 运行终端客户端
启动交互式界面，传递您的配置文件和目标模型：
```bash
ollmcp --servers-json config.json --model llama3.1
```
###### 一旦终端 UI 加载：
1. 从模型列表中选择目标 Llama 模型。
2. 提交需要实时网络数据的提示 — 例如 *"使用 SERPHouse 查找 'best developer tools' 的谷歌搜索结果。"*
3. 观察本地 Llama 模型调用 SERPHouse 工具并将实时 SERP 数据转换为对话式答案。
### 兼容的模型
以下 Ollama 模型与工具使用配合良好：
- gemma4
- qwen3.5
- lfm2.5-thinking
- llama3.2
- mistral
有关具有工具使用功能的 Ollama 模型的完整列表，请访问官方 [Ollama 模型](https://ollama.com/search?c=tools) 页面。
有关也可以处理工具返回的图像的模型，请参阅 Ollama [视觉模型](https://ollama.com/search?c=vision) 页面。
---
## 故障排除
| 问题 | 修复 |
|-------|-----|
| 缺少 API 密钥 | 在 `/mcp` 请求上发送 `SERPHOUSE_API` 头 |
| 无效密钥 | 在 [SERPHouse 仪表盘](https://serphouse.com) 中验证您的密钥 |
| 信用耗尽 | 使用 `serphouse_account_info` 检查余额 |
| 位置错误 | 对于谷歌和 Bing 工具，包括 `loc` 或 `loc_id`（两者不可同时使用）；使用 `serphouse_location_search` 解析 ID。雅虎 SERP 工具不需要位置。 |
| 连接被拒绝 | 确认服务器正在运行且 URL/端口正确 |
---
## 贡献
欢迎贡献。请保持更改的焦点并匹配现有的代码风格。
```bash
git checkout -b feature/your-feature
npm install
# 进行更改
npm run typecheck
git commit -m "添加您的功能"
git push origin feature/your-feature
```
然后打开拉取请求。如果您更改了设置或配置，请更新此 README。
---
## 许可证
[MIT 许可证](LICENSE) — 版权所有 SERPHouse。
