# seo_research

> SEO 数据。

URL: https://mcp-docs.opennomos.com/zh/docs/tools/research/seo_research

> SEO 数据。action=serp：直接返回某个关键词的 Google 自然搜索结果（约 8 秒，$0.002）。action=keyword_suggestions：返回带 search_volume、cpc、competition、difficulty 和 intent 的关键词结果（约 3 秒，约 $0.013）。action=keyword_difficulty：给出关键词的难度（约 3 秒，约 $0.012）。>
> location_code 取国家名（'United States'、'China'、'Hong Kong'）或数字代码，默认 US;language_code 默认 'en'。depth 控制 SERP 的深度；limit 控制关键词建议的数量。

> 以上是服务端发布的英文描述的译文；英文原文见[英文页](https://mcp-docs.opennomos.com/docs/tools/research/seo_research.md)。工具名、参数名和取值保持原样。

| 字段 | 值 |
| --- | --- |
| 工具包 | SEO & AI visibility (`seo`) |
| 每次调用的预估成本 | ~$0.013（上游成本；各 action 的具体数字见描述） |
| 工具包每月上限 | 上游成本 $3（不向用户显示） |
| 项目 | 可选（`project` 或 `X-OpenNomos-Project`）；只是把项目 id 附在结果里 |

## 参数

| 参数 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `project` | 否 | `string` | 项目 slug 或 id。省略则用凭据或工作区的默认项目。 |
| `action` | 是 | `"serp"` \| `"keyword_suggestions"` \| `"keyword_difficulty"` | serp = Google 自然搜索结果；keyword_suggestions = 带搜索量/cpc/难度的相关关键词；keyword_difficulty = 给定关键词的难度。 |
| `keyword` | 否 | `string` | 种子关键词，例如 'ai crm'。serp 和 keyword_suggestions 使用（keyword_difficulty 也可把它当作单个关键词）。 |
| `keywords` | 否 | `string[]` | 仅 keyword_difficulty：要打分的关键词，例如 ['ai crm', 'sales copilot']。 |
| `location_code` | 否 | `integer (≥ 1) \| string` | 从哪里搜索：国家名（如 "United States"、"China"、"Hong Kong"、"Japan"）、两位国家代码（"US"、"CN"），或数字形式的 DataForSEO 地区代码（如 2840）。默认 United States。 |
| `language_code` | 否 | `string` | 搜索语言代码，例如 'en'、'de'、'ja'。默认 'en'。 |
| `depth` | 否 | `integer (≥ 1, ≤ 100)` | 仅 serp：要多少条结果。默认 10。 |
| `limit` | 否 | `integer (≥ 1, ≤ 100)` | 仅 keyword_suggestions：最多返回多少个关键词。默认 20。 |

## 示例调用

```json
{
  "action": "keyword_suggestions",
  "keyword": "ai crm",
  "location_code": "United States",
  "limit": 20
}
```

REST:`POST https://service.opennomos.com/v1/tools/seo_research`，以上 JSON 作为请求体。MCP:`tools/call`,`name: "seo_research"`，以上 JSON 作为 `arguments`。

## 示例结果

示例里的值是示意性的；结构来自服务端代码。

```json
{
  "results": [
    {
      "keyword": "ai crm software",
      "search_volume": 5400,
      "cpc": 12.4,
      "competition": 0.61,
      "difficulty": 38,
      "intent": "commercial"
    },
    "…"
  ]
}
```

## 说明

- 三个 action:`serp`（Google 自然结果，约 8 秒、$0.002）、`keyword_suggestions`（约 3 秒、约 $0.013）和 `keyword_difficulty`（约 3 秒、约 $0.012）。
- `location_code` 接受国家名（"United States"、"China"、"Hong Kong"）、两位国家代码（"US"、"CN"）或数字形式的 DataForSEO 代码。名称未知时，返回的错误里会列出示例。
- `serp` 只返回自然结果；实际返回少于 `depth` 时，`note` 会说明。
- 每个关键词行里的具体字段名来自服务商，没有做规范化。

## 错误

上游出问题时，会在一个**正常结果里**以 `error`、`reason` 和 `action` 报告（适用时还有 `tool` / `retry_after_seconds`）。对 `search_signals`，这会按来源分别出现。见[错误](https://mcp-docs.opennomos.com/zh/docs/reference/errors.md)。

这个工具属于 **SEO & AI visibility** 工具包。如果该包没有启用，调用会以 `pack_required`（HTTP 403）失败；如果该包的每月上游成本上限已用完，会以 `soft_limit`（HTTP 429）失败。两者都带 `action: "give_up_and_tell_user"` 和控制台 URL。