SERPHouse MCP

---

目录

• 为什么选择 SERPHouse MCP
• 快速开始（托管版）
• 身份验证
• 你可以询问什么
• 工具概览
• 本地自托管
• 使用 Docker 自托管
• 搭配本地 Llama 模型使用（Ollama）
• 故障排除
• 参与贡献
• 许可证

---

为什么选择 SERPHouse MCP

21 个 MCP 工具	实时 Google、Bing 和 Yahoo SERP、Google 垂直搜索和账户查询——全部通过带类型的架构提供
无需编写胶水代码	助手会选择合适的工具；只需用自然语言描述需求
托管或自托管	使用托管端点 https://mcp.serphouse.com/mcp，或在自己的基础设施上运行服务
内置上下文	MCP 资源（serphouse_capabilities、serphouse_constraints、serphouse_examples）会自动教 AI 使用规则

---

快速开始（托管版）

最快的方式——无需构建，也无需维护服务。

1. 从 SERPHouse Dashboard 获取 API 密钥。

2. 在 MCP 客户端配置中添加服务，并使用基于请求头的身份验证或基于 URL 的身份验证（详情请参阅身份验证）。

请求头（推荐）：

{
  "mcpServers": {
    "serphouse": {
      "url": "https://mcp.serphouse.com/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

URL 路径：

{
  "mcpServers": {
    "serphouse": {
      "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

3. 开始聊天。让助手搜索 Google、Bing 或 Yahoo，查询地点、获取职位信息或查看账户；助手会将请求路由到正确的工具。

一键安装： 使用上方的 Install in VS Code 或 Install in Cursor 徽章，然后将占位 API 密钥替换为你自己的密钥。

---

身份验证

服务器接受两种方式传入 SERPHouse API 密钥。请选择适合你的 MCP 客户端的方式。

方法	端点	如何传入密钥
请求头（推荐）	POST /mcp	请求头 SERPHOUSE_API: <api_key>
URL 路径	POST /{apiKey}/mcp	将密钥嵌入 URL 路径

无需密钥即可发现工具和资源。仅在调用 SERPHouse API 工具时需要 API 密钥。

选项 A：请求头（推荐）

适用于支持自定义请求头的 MCP 客户端。密钥不会出现在 URL 和服务器访问日志中。

{
  "mcpServers": {
    "serphouse": {
      "url": "https://mcp.serphouse.com/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

可自托管示例：

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

选项 B：URL 路径

适用于仅支持 URL、无法发送自定义请求头的客户端。

{
  "mcpServers": {
    "serphouse": {
      "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

可自托管示例：

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

注意： 基于 URL 的身份验证会将 API 密钥放在请求路径中，因此密钥可能出现在代理日志或浏览器历史记录中。尽可能优先使用请求头方式。

---

你可以询问什么

面向需要在 AI 工作流中使用实时搜索数据的 SEO 团队、代理机构和 SaaS 营销人员——无需仪表板、脚本或切换上下文。

使用场景	提示词示例
跟踪排名	“我们在 Google 美国桌面端搜索 ‘crm software’ 时排名第几？”
超越竞争对手	“在伦敦，谁占据了 ‘project management software’ 的前 5 个位置？”
占据本地搜索	“芝加哥搜索 ‘emergency plumber’ 时，Google Local 的热门结果有哪些？”
发现关键词	“Autocomplete 对 ‘best saas for’ 有哪些建议？”
监控排名位置	“在 NYC 对我们的品牌进行一次移动端 Bing SERP 检查，并报告我们的排名。”
覆盖多个搜索引擎	“比较 Yahoo 和 Google 上 ‘electric vehicles’ 的新闻搜索结果。”

---

工具概览

服务器提供 21 个工具，分为五个类别。Google 和 Bing SERP 请求必须且只能指定一个位置字段——loc（例如 Austin,Texas,United States）或 loc_id（通过 serphouse_location_search 获取）。在这些端点上，不能同时传入两者，也不能两者都省略。Yahoo SERP 工具不需要位置。

参考

工具	描述
serphouse_domain_list	支持的 Google、Bing 和 Yahoo 搜索域名
serphouse_language_list	各搜索引擎类型对应的语言代码
serphouse_location_search	将城市／国家名称解析为 loc_id
serphouse_account_info	账户余额和使用情况

Google SERP

工具	描述
serphouse_google_web	Google 网页搜索
serphouse_google_image	Google 图片搜索
serphouse_google_news	Google 新闻搜索
serphouse_google_shop	Google 购物搜索
serphouse_serp_google_advanced	高级 Google SERP，支持扩展参数（最多 100 条结果）

Bing SERP

工具	描述
serphouse_bing_web	Bing 网页搜索
serphouse_bing_image	Bing 图片搜索
serphouse_bing_news	Bing 新闻搜索

Yahoo SERP

工具	描述
serphouse_yahoo_web	Yahoo 网页搜索
serphouse_yahoo_image	Yahoo 图片搜索
serphouse_yahoo_news	Yahoo 新闻搜索

Google 垂直搜索

工具	描述
serphouse_google_jobs	Google 职位搜索
serphouse_google_autocomplete	Google Autocomplete 建议
serphouse_google_videos	Google 视频搜索结果
serphouse_google_short_videos	Google 短视频（Shorts）
serphouse_google_forums	Google 论坛搜索结果
serphouse_google_local	Google Local／地图搜索结果

---

在本地自托管

在你的计算机上运行服务器，以便完全掌控或进行本地开发。

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 — 通过 SERPHOUSE_API 标头传递 API 密钥
• POST /{apiKey}/mcp — 在 URL 路径中传递 API 密钥

将 MCP 客户端指向本地实例（两种方式请参阅身份验证）：

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

或使用基于 URL 的身份验证：

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

命令

命令	描述
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	启动针对 stdio 服务器的 MCP Inspector 以进行调试
npm run typecheck	进行类型检查，不生成文件

健康检查：GET http://localhost:3000/health

服务器选项

变量	默认值	描述
PORT	3000	HTTP 监听端口
HOST	0.0.0.0	HTTP 绑定地址

身份验证同时支持标头和 URL 路径。请参阅身份验证。

---

使用 Docker 自托管

在本地通过 Docker 运行 MCP 服务器，无需安装 Node.js。

docker compose up -d

服务器运行于 http://localhost:3000/mcp（标头身份验证）或 http://localhost:3000/{apiKey}/mcp（URL 身份验证）。

使用身份验证中的任一方式连接 MCP 客户端：

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

或者：

{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:3000/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

---

与本地 Llama 模型（Ollama）搭配使用

使用 ollmcp 将 SERPHouse MCP Server 接入本地 Llama 模型（例如 Llama 3.1 或 3.2）。它是一个交互式终端界面客户端，可将实时搜索引擎能力直接带入本地大模型工作流。

前置条件

要求	备注
支持工具调用的 Llama 模型	已通过 Ollama 安装并运行的、支持工具调用的模型（例如 llama3.1、llama3.2）
Python 3.10+	运行 ollmcp 终端客户端所需
Node.js	通过 npx 运行 SERPHouse MCP 服务器所需

1. 安装 ollmcp

ollmcp 是一个 Python 客户端，因此请使用 pip 全局安装：

pip install --upgrade ollmcp

2. 创建 config.json 文件

客户端需要一个配置文件来指定如何连接 SERPHouse 服务器并传递 API 凭据。请在工作文件夹中创建 config.json，并使用身份验证中的任一方式：

{
  "mcpServers": {
    "serphouse-mcp": {
      "url": "https://mcp.serphouse.com/mcp",
      "headers": {
        "SERPHOUSE_API": "YOUR_SERPHouse_API_KEY"
      }
    }
  }
}

或使用基于 URL 的身份验证：

{
  "mcpServers": {
    "serphouse-mcp": {
      "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}

将 YOUR_SERPHouse_API_KEY 替换为你从 SERPHouse Dashboard 获取的有效密钥。

3. 运行终端客户端

启动交互式界面，并传入配置文件和目标模型：

ollmcp --servers-json config.json --model llama3.1

终端界面加载后：

1. 从模型列表中选择目标 Llama 模型。
2. 提交需要实时网络数据的提示词，例如 “使用 SERPHouse 查找 ‘best developer tools’ 的 Google 热门结果。”
3. 查看本地 Llama 模型调用 SERPHouse 工具，并将实时 SERP 数据转化为对话式回答。

兼容模型

以下 Ollama 模型适用于工具调用：

• gemma4
• qwen3.5
• lfm2.5-thinking
• llama3.2
• mistral

如需查看支持工具调用的 Ollama 模型完整列表，请访问官方 Ollama models 页面。

如需了解还能处理工具返回图像的模型，请参阅 Ollama 的 vision models 页面。

---

故障排除

问题	解决方法
缺少 API 密钥	在 POST /mcp 请求中发送 SERPHOUSE_API 标头，或使用 POST /{apiKey}/mcp，将密钥放在 URL 路径中
密钥无效	在 SERPHouse 控制面板中验证你的密钥
额度耗尽	使用 serphouse_account_info 检查余额
位置错误	对于 Google 和 Bing 工具，请包含 loc 或 loc_id（不能同时包含两者）；使用 serphouse_location_search 查询 ID。Yahoo SERP 工具不需要位置。
连接被拒绝	确认服务正在运行，且 URL 和端口正确

---

贡献

欢迎贡献。请确保修改范围明确，并遵循现有代码风格。

git checkout -b feature/your-feature
npm install
# make changes
npm run typecheck
git commit -m "Add your feature"
git push origin feature/your-feature

然后发起 Pull Request。如果更改了设置或配置，请更新此 README。

---

许可证

MIT License — 版权所有 SERPHouse。