Thordata SERP MCP Server

Thordata MCP 服务

将 Thordata SERP 接入兼容 MCP 的 AI Agent 和客户端，实现实时搜索、使用历史记录和统计数据。

Thordata SERP MCP 服务通过模型上下文协议（MCP）提供 Thordata 搜索功能，让你轻松将实时搜索工具集成到 Agent、工作流和 MCP 客户端中。除了实时 SERP 请求，它还提供搜索历史记录、使用统计数据和引擎架构资源，支持更丰富的集成。

快速开始

大多数用户会连接 托管的 Thordata MCP 端点——无需安装或本地构建。你只需要一个 Thordata SERP API 密钥。

1. 获取 API 密钥

在 Thordata 注册，然后从控制面板获取 SERP API 密钥。

2. 连接 MCP 客户端

将 MCP 客户端指向托管端点，并将 API 密钥放入 URL 路径中。每次请求都会使用你的密钥；Thordata 不会代表你存储共享凭据。

默认连接 URL 为：

https://mcp.thordata.com/YOUR_API_KEY/mcp

将 YOUR_API_KEY 替换为你的 Thordata SERP API 密钥，并使用以下 MCP 客户端配置：

{
  "mcpServers": {
    "thordata": {
      "url": "https://mcp.thordata.com/YOUR_API_KEY/mcp"
    }
  }
}

如果你的客户端支持自定义标头，也可以使用 Bearer 配置：

{
  "mcpServers": {
    "thordata": {
      "url": "https://mcp.thordata.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

若要通过 Claude Code 一行安装，请运行：

claude mcp add --transport http thordata https://mcp.thordata.com/YOUR_API_KEY/mcp

3. 发起首次请求

典型的调用流程如下：

1. 读取 thordata://engines 资源，查看支持的引擎。
2. 读取 thordata://engines/<engine-key>，获取所需引擎的信息。
3. 根据该引擎的架构构建 params。
4. 调用 search 工具。

功能

• search — 在任何受支持的引擎上执行实时 SERP 搜索。
• list_engines — 查看当前引擎列表、查询字段和架构资源。
• history — 查询你自己账户的 SERP 请求历史记录。
• statistics — 查询你自己账户的 SERP 使用统计数据。

历史记录和统计数据仅限你发送的 API 密钥对应的账户；你无法查询其他用户的数据。

身份验证

支持以下令牌传递方式：

• 默认方式：https://mcp.thordata.com/YOUR_API_KEY/mcp（令牌位于路径中）。
• 可选方式：通过 https://mcp.thordata.com/mcp 发送 Authorization: Bearer YOUR_API_KEY。
• 兼容方式：X-Thordata-Serp-Token: YOUR_API_KEY。

注意：

• 托管的路径令牌 URL 是默认连接方式。
• 对于支持自定义标头的客户端，可使用 Bearer 方式。
• 路径令牌可能出现在访问日志和来源页中，因此托管端点始终使用 HTTPS。
• 不接受查询字符串令牌。
• 每次请求都会转发你的 API 密钥，且不会将其包含在 MCP 结果元数据中；返回数据和错误文本中的密钥会被隐藏。
• 你的引擎可用性和访问级别由 Thordata SERP 服务根据你的 API 密钥确定。

工具

list_engines

返回当前架构版本、受众、默认引擎、引擎列表、每个引擎的查询字段及其资源 URI。

search

执行 Thordata SERP 搜索请求。

参数	必填	描述
engine	否	Thordata 引擎键，例如 google、google_images、google_maps 或 bing。省略时使用架构默认值。
q	否	便捷搜索输入。如果引擎声明的查询字段不是 q，则会映射到该字段。
json	否	响应格式：1、2 或 3。默认为 1。
params	否	引擎资源定义的特定引擎参数。系统会忽略不受支持的键。
response_mode	否	complete 或 compact。Compact 模式会移除常见元数据字段。

成功的结果使用以下封装格式：

{
  "ok": true,
  "status": 200,
  "engine": "google",
  "data": {}
}

history

查询 API 密钥所有者的 SERP 请求历史记录。

参数	必填	描述
page	否	页码。默认为 1。
page_size	否	每页数量。默认为 20。
search_query	否	搜索查询筛选条件。
search_engine	否	Thordata 引擎密钥筛选条件。
status	否	all、success 或 error。默认为 all。
start_time	否	Unix 秒级时间戳的开始时间。
end_time	否	Unix 秒级时间戳的结束时间。
timezone	否	IANA 时区或数字偏移量。

statistics

查询 API 密钥所有者的 SERP 使用统计信息。

参数	必填	描述
start_date	是	YYYY-MM-DD 格式的开始日期。
end_date	是	YYYY-MM-DD 格式的结束日期。
engines	否	以逗号分隔的引擎字符串或字符串数组。
timezone	否	IANA 时区或偏移量，例如 +08:00。

资源

资源	描述
thordata://engines	当前支持的引擎定义索引。
thordata://engines/<engine-key>	某个引擎的分组、字段、控件、默认值、选项和条件。

构建正确的参数

只会发送所选引擎架构中声明的字段。构建请求时：

• 最终的 engine 值始终是所选的引擎密钥。
• 顶层的 q 和 json 会覆盖 params 中同名的值；json 默认为 1。
• 会省略空值、空字符串和空数组。数值 0 和布尔值 false 会保留。

按字段类型划分的序列化规则：

• string 和 options 类型的值会原样发送；Google Flights 的 departure_id 和 arrival_id 会规范化为大写。
• boolean（switch）类型的值会序列化为 true 或 false。
• number 类型的值会序列化为字符串。
• array（multi_select）类型的值会以逗号连接，且每个元素都必须是标量。当前架构中，国家/地区限制字段 cr 声明为数组，因此会按原样以逗号连接后发送。
• object 类型的值会序列化为 JSON。
• 未知参数会被忽略，所选引擎始终具有决定权。

响应格式：

• json=1：仅返回结构化 JSON。
• json=2：在支持时返回 JSON 和 HTML。
• json=3：仅在支持时返回 HTML。

complete 模式返回完整结果；compact 模式会剔除常见元数据字段。

错误处理

服务会规范化响应，并将故障作为 MCP 工具错误呈现：

• 成功的业务代码会被视为成功；所有其他非成功代码、非 2xx 响应、传输故障和错误文本都会被视为故障。
• 双重编码的 JSON 负载会被解包，并会在向你返回结果或错误之前对用户令牌进行脱敏。