文档中心

欢迎使用 SEO Agent 文档中心。SEO Agent 的品牌口号是：让AI帮你提升独立站流量。这里重点说明 MCP 接入、API 调用、GEO 分析、关键词研究和授权数据诊断，帮助独立站卖家、SEO 公司和外贸企业把 SEO 能力接入 AI 工作流。

入门指南

SEO Agent 是面向 AI 时代的 SEO 工作流平台，优先支持 MCP、API 数据接入、GEO/AI 搜索可见度和关键词研究，也支持排名查询、竞品分析、站内审计、已授权 GSC 搜索表现/高级诊断和已授权 GA4 流量质量诊断。你可以通过网页对话、API 或 MCP 三种方式使用。

快速上手

第一步：注册账号

访问 SEO Agent 首页，点击右上角“注册/登录”按钮，填写邮箱、密码和确认密码即可完成注册。注册过程简单快速，仅需不到 1 分钟。

第二步：充值余额

登录后进入，选择合适的充值档位完成支付。SEO Agent 采用按量付费模式，最低 30 元起充，余额长期有效，不会过期清零。

第三步：开始使用

普通分析可以直接在对话框输入目标，例如"分析我的独立站在美国英文市场有哪些 SEO 机会"。如果你要让 Codex 等 AI 工具接手连续任务，优先配置 MCP；如果你要接入脚本、客户报表或内部系统，优先使用 API。

API 概览

SEO Agent 提供完整的 REST API 接口，支持把 SEO 数据能力集成到脚本、客户报表或内部系统中。MCP 和 API 共用同一个 SEO Agent API Key：MCP 适合 AI 工具自动调用，API 适合系统和脚本稳定调用。API / MCP 主要返回标准化数据和扣费信息；如果需要完整顾问报告，可以在网页对话中生成，或让你自己的 AI 工作流基于返回数据继续整理分析初稿。

推荐调用流程

1. 在个人资料页创建 API Key，并选择允许调用的接口范围。
2. 决定接入方式：AI 工具用 MCP，脚本、报表和内部系统用 API。
3. 正式查询前先调用 /api/dev/estimate 或传入 dryRun: true 预估费用。
4. 确认参数、市场和余额后执行正式查询，并从响应的 data 与 billing 读取结果和扣费信息。

支持的 API 接口

• MCP 接入 - 让 Codex 等 AI 工具按目标调用 SEO Agent，不需要手动记接口路径
• API 接入 - 把标准化 SEO 数据接入脚本、客户报表和内部系统
• GEO / AI 搜索可见度 - 查询 Google AI Overview 与 ChatGPT 的当前提及、高频来源、历史趋势、新增/丢失、多目标对比和品牌品类格局
• GEO 深度审计 - 检查页面可引用性、AI 爬虫、llms.txt、Schema 和品牌平台建议，可选返回 PDF 报告
• 关键词研究 - 查询种子词的搜索量、竞争度、搜索意图和相关关键词
• 深度关键词研究 - 补全 KD、CPC、趋势、问题词、商业价值和关键词分组
• 域名个性化关键词机会 - 结合目标域名已有排名判断应优化旧页面还是新建页面
• 域名关键词 - 查询指定域名当前已有自然排名关键词
• 竞品关键词差距 - 对比你的网站与竞品域名之间的关键词差距
• 竞品关键词策略分析 - 输入种子关键词，整理前排同行和竞品高搜索量关键词
• 关键词排名查询 - 查询指定域名在某个关键词下的自然排名
• 站内审计 - 使用 seoagent 内置爬虫，审计网站技术 SEO 和站内 SEO
• GSC 搜索表现与诊断 - 读取已授权站点的点击、曝光、CTR、排名、内容衰退、关键词蚕食和行动计划
• GA4 流量质量诊断 - 读取已授权媒体资源的会话、渠道、落地页、互动率、跳出率和关键事件，输出落地页机会、渠道诊断和行动计划
• 账户余额 - 查询当前 API Key 对应的账户余额和可用额度
• 消费记录 - 查询 API 调用历史消费记录

认证方式

所有 API 请求都需要在请求头中携带 API Key 进行认证。你可以在个人设置页面创建和管理 API Key。

示例代码

curl -X POST https://www.seoagent.vip/api/dev/keyword-research \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "running shoes",
    "location": "United States",
    "language": "English"
  }'

费用预估 API

正式查询前预估最高费用，不执行查询，不扣费。支持所有查询类接口的费用预估。

estimate 到正式调用示例

# 1. 先预估费用
curl -X POST https://www.seoagent.vip/api/dev/estimate \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "domain-keyword-opportunities",
    "params": {
      "domain": "example.com",
      "keyword": "running shoes",
      "location": "United States",
      "language": "English",
      "limit": 10
    }
  }'

# 2. 确认后正式查询
curl -X POST https://www.seoagent.vip/api/dev/domain-keyword-opportunities \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "keyword": "running shoes",
    "location": "United States",
    "language": "English",
    "limit": 10
  }'

关键词研究 API

查询种子词的搜索量、竞争度、搜索意图和相关关键词，帮助判断哪些关键词值得优先做。

深度关键词研究 API

在基础关键词研究上补充关键词难度、CPC、趋势、问题词、商业价值、建议页面类型和关键词分组，适合做内容规划和页面矩阵。

主要返回字段

• keywords：关键词明细，包含搜索量、CPC、竞争度、KD、趋势分、问题词、商业分、建议页面类型和优先级。
• groups：关键词分组，包含分组名、主关键词、总搜索量、平均难度、商业词数量、问题词数量和推荐页面类型。
• history：关键词历史趋势摘要。

域名个性化关键词机会 API

输入目标域名和种子关键词，SEO Agent 会结合关键词扩展数据和目标域名已有自然排名，判断该网站优先做哪些词、当前是否已有匹配页面，以及建议优化旧页面还是新建页面。

主要返回字段

• keywords：个性化机会词，包含机会分、当前排名、匹配页面、难度适配分、推荐动作和 P0/P1/P2 优先级。
• groups：按主题合并后的关键词分组，帮助判断应该做几个页面。
• domainMetrics：目标域名当前样本中的排名能力指标。

域名关键词 API

查询指定域名当前已有自然排名关键词，了解网站的关键词覆盖情况。

竞品关键词差距 API

对比你的网站与竞品域名之间的关键词差距，找出竞品有排名而自己缺失的关键词机会。

竞品关键词策略 API

输入一个种子关键词，自动整理最多 5 个前排同行网站和每个竞品最多 10 个高搜索量排名关键词。

排名查询 API

查询指定域名在某个关键词下的自然排名位置。

GEO 可见度 API

使用新版 LLM Mentions 查询 Google AI Overview 或 ChatGPT 的当前提及、目标指标、高频来源域名与页面。可通过 platform 选择 google 或 chat_gpt，通过 lite: true 使用轻量查询。

GEO 趋势、对比与品牌格局 API

以下接口均使用新版 LLM Mentions，不再调用旧端点。默认平台为 google；指定 chat_gpt 时仅支持 United States / English。

{
  "domain": "yourdomain.com",
  "platform": "google",
  "dateFrom": "2026-01-01",
  "dateTo": "2026-07-01",
  "location": "United States",
  "language": "English"
}

{
  "targets": ["yourdomain.com", "competitor-a.com", "competitor-b.com"],
  "platform": "google",
  "location": "United States",
  "language": "English"
}

GEO 深度审计 API

审计单个网站或页面的 GEO 基础，包括页面可引用性、AI 爬虫访问状态、llms.txt 结构、Schema 建议、品牌平台建议和综合评分。llms.txt 属于辅助说明文件，不代表 AI 搜索一定引用；报告会把已检测事实和优化建议分开。

站内审计 API

使用 seoagent 内置爬虫，先读取 robots.txt 与 Sitemap 统计预计页面数，再审计网站页面、标题、描述、H1、canonical、内外链、图片 alt、响应速度和索引问题。100 页以内确认费用后同步执行，超过 100 页确认费用后自动创建后台异步任务。

站内审计（异步）API

大于 100 页的网站会使用异步站内审计：SEO Agent 在后台按 Sitemap 页面持续抓取，立即返回任务 ID。返回结果会说明预计时间、最高费用以及如何查询；支持通过 callbackUrl 接收完成通知，或通过查询接口获取实时进度和最终报告。

GSC 搜索表现与诊断 API

读取用户已授权站点的 GSC 搜索表现数据，用于把真实点击、曝光、CTR、平均排名、内容衰退、关键词蚕食和优先级行动计划接入 Codex、脚本或内部报表。使用前需要先在个人资料页完成 GSC 连接，并在创建 API Key 时勾选对应 GSC 权限。

curl -X POST https://www.seoagent.vip/api/dev/gsc-search-analytics \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dimensions": ["query", "page"],
    "startDate": "2026-06-01",
    "endDate": "2026-06-28",
    "rowLimit": 1000
  }'

GA4 流量质量诊断 API

读取用户已授权媒体资源的 GA4 数据，用于把会话、用户、渠道、落地页、互动率、跳出率、关键事件和转化承接诊断接入 Codex、脚本或内部报表。使用前需要先在个人资料页完成 GA4 连接，并在创建 API Key 时勾选对应 GA4 权限。

curl -X POST https://www.seoagent.vip/api/dev/ga4-report \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dimensions": ["landingPagePlusQueryString"],
    "metrics": ["sessions", "engagementRate", "bounceRate", "keyEvents"],
    "startDate": "2026-06-01",
    "endDate": "2026-06-28",
    "limit": 100
  }'

账户余额 API

查询当前 API Key 对应的账户余额、可用额度和套餐信息。

消费记录 API

查询 API 调用历史消费记录，包含接口类型、调用时间、扣费金额和调用状态。

MCP 概览

MCP（Model Context Protocol）是让 AI 工具可以直接调用外部能力的协议。通过 MCP 接入，支持 MCP 的 AI 工具（如 Codex）可以自动理解你的目标，主动调用 SEO Agent 的标准化数据能力，完成查询、整理和分析初稿等连续工作流。对于独立站卖家、SEO 公司和外贸企业来说，它的价值是减少人工进入多个工具查数、复制和整理表格的时间。

MCP 的优势

• 自动化工作流 - AI 工具按目标自动调用能力，不需要人工切换工具
• 更适合 SEO 公司批量交付 - 可把多个客户的关键词、GEO、竞品和授权数据整理成初稿
• 更适合独立站增长 - 可围绕产品词、目标国家和竞品持续查找页面机会
• 自然语言交互 - 用自然语言描述任务，AI 理解后自动执行

支持的 MCP 工具

• seoagent_keyword_research：轻量关键词研究，适合快速查搜索量、竞争度、意图和相关词。
• seoagent_keyword_intelligence：深度关键词研究，返回 KD、CPC、趋势、问题词、商业价值和关键词分组。
• seoagent_domain_keyword_opportunities：域名个性化关键词机会，结合域名已有排名判断优化旧页面还是新建页面。
• seoagent_domain_keywords：查询指定域名当前已有自然排名关键词。
• seoagent_competitor_gap：对比我方域名和竞品域名的关键词差距。
• seoagent_competitor_keyword_strategy：从种子关键词整理前排同行和竞品高搜索量关键词。
• seoagent_serp_rank_query：查询指定域名在指定关键词下的排名位置。
• seoagent_geo_visibility：查询品牌、主题或域名的 GEO / AI 搜索可见度。
• seoagent_geo_visibility_history：查询 AI 可见度历史趋势。
• seoagent_geo_visibility_delta：查询 AI 可见度变化量。
• seoagent_geo_visibility_new_lost：查询新增与丢失 AI 提及。
• seoagent_geo_visibility_comparison：对比最多 10 个目标的 AI 可见度。
• seoagent_geo_brand_landscape：查询 AI 高频品牌和品牌品类格局。
• seoagent_geo_deep_audit：执行 GEO 深度审计，返回页面可引用性、AI 爬虫、llms.txt、Schema 和可选 PDF 报告。
• seoagent_site_audit：先读取 Sitemap 返回预计页数、最高费用和预计时间；100 页以内确认后同步审计，超过 100 页确认后转为后台异步分批审计。
• seoagent_get_site_audit_task：使用任务 ID 查询异步审计进度；任务完成后读取包含完整性说明的最终报告。
• seoagent_gsc_sites：查询已授权的 GSC 站点列表和默认站点。
• seoagent_gsc_search_analytics：查询 GSC 搜索表现，包括点击、曝光、CTR 和平均排名。
• seoagent_gsc_keyword_opportunities：识别高曝光低 CTR 和 Quick Win 关键词机会。
• seoagent_gsc_page_opportunities：识别需要优先优化的页面机会。
• seoagent_gsc_performance_summary：对比当前周期和上一周期的 GSC 表现，输出增长和下降来源。
• seoagent_gsc_content_decay：发现点击或排名明显下滑的页面和查询。
• seoagent_gsc_cannibalization：识别同一查询被多个页面共同承接的关键词蚕食风险。
• seoagent_gsc_action_plan：综合 GSC 诊断结果生成 P0/P1/P2 优先级行动清单。
• seoagent_ga4_properties：查询已授权的 GA4 媒体资源列表和默认媒体资源。
• seoagent_ga4_report：查询 GA4 报表数据，包括会话、用户、浏览、互动率、跳出率和关键事件。
• seoagent_ga4_traffic_summary：汇总 GA4 流量质量、渠道、设备和国家表现。
• seoagent_ga4_landing_page_opportunities：识别有访问但承接或转化偏弱的落地页机会。
• seoagent_ga4_channel_insights：诊断渠道流量质量和关键事件表现。
• seoagent_ga4_action_plan：综合 GA4 诊断结果生成 P0/P1/P2 优先级行动清单。
• seoagent_search_consultant_knowledge：按需检索 SEO 顾问方法论、场景判断和官方实践摘要；策略、诊断和报告任务可自动使用。MCP 会要求 AI 将结果整理成自然、易懂的客户语言，而不是直接展示工具数据。
• seoagent_get_consultant_knowledge_card：在需要更细的判断边界、执行流程或验收标准时读取一张已检索到的知识卡。
• seoagent_estimate：正式查询前预估费用和缓存命中情况。

MCP 配置指南

前置条件

1. 已注册 SEO Agent 账号并完成首次充值
2. 在个人设置页面创建了 API Key
3. 使用支持 MCP 协议的 AI 工具（如 Codex）

推荐方式：在 Codex 对话中完成配置

打开任意一个可信任的 Codex 对话，将下方 YOUR_SEO_AGENT_API_KEY 替换为你自己的 SEO Agent API Key 后直接发送。Codex 会把远程 MCP 配置写入本机的 ~/.codex/config.toml，保留已有的 MCP 配置。

请帮我在本机 Codex 中添加 SEO Agent 远程 MCP。

请只修改 ~/.codex/config.toml，不要删除或覆盖已有配置；
将以下配置追加到文件末尾，写入后检查 TOML 语法：

[mcp_servers.seoagent]
enabled = true
url = "https://www.seoagent.vip/mcp"

[mcp_servers.seoagent.http_headers]
Authorization = "Bearer YOUR_SEO_AGENT_API_KEY"

不要在回复中回显我的 API Key。完成后告诉我是否需要新开对话或重启 Codex 才能加载。

如果你习惯自己编辑配置文件，可将下方内容追加到 ~/.codex/config.toml。这是 Codex 当前使用的远程 MCP 格式，不是旧版的 mcpServers JSON 或本地 Node 启动脚本格式。

[mcp_servers.seoagent]
enabled = true
url = "https://www.seoagent.vip/mcp"

[mcp_servers.seoagent.http_headers]
Authorization = "Bearer YOUR_SEO_AGENT_API_KEY"

Codex 接入指南

在 Codex 对话中完成配置后，你就可以用自然语言让 Codex 调用 SEO Agent，完成独立站 SEO、GEO、关键词研究和客户报告初稿等任务。

加载与验证

1. 让 Codex 完成配置后，新开一个对话；如未出现工具，再重启 Codex。
2. 在新对话中发送：检查 SEO Agent MCP 是否已连接，并只列出可调用的 SEO 工具名称。
3. 确认连接后，再发送真实业务任务；首次建议先用一个小范围关键词或域名查询验证权限、市场和余额。

在 Codex 中使用

配置完成后，你可以直接在 Codex 中提问，例如：

• "帮我分析 example.com 这个独立站在美国英文市场的 SEO 机会"
• "查询 running shoes 这个关键词的搜索量和竞争度，并判断适合产品页还是博客页"
• "深度分析 running shoes 的关键词分组、商业词和问题词"
• "分析 example.com 围绕 running shoes 在美国英文市场的个性化关键词机会"
• "对比 example.com 和 competitor.com 的内容差距"
• "给 example.com 做一次站内 SEO 审计"
• "用我已连接的 GSC 数据，找出最近 28 天高曝光低点击和排名 8-20 名的关键词机会"
• "用我已连接的 GA4 数据，找出最近 28 天有访问但关键事件偏弱的落地页"

常见问题

API 调用有速率限制吗？

有的。默认 API 调用速率限制为每分钟 240 次。如果需要更高的速率限制，请联系我们的销售团队定制企业方案。

如何预估 API 调用费用？

你可以使用 /api/dev/estimate 端点预估调用费用，也可以在调用时设置 dryRun: true 参数来获取预估费用而不实际执行。

API Key 安全吗？

API Key 使用加密存储，创建时只显示一次完整密钥，后续无法查看。你可以为每个 Key 设置不同的接口权限（scope）、消费额度上限和有效期，降低风险。

支持哪些编程语言的 SDK？

目前我们提供 REST API 接口，你可以使用任何支持 HTTP 请求的编程语言调用。官方 SDK 正在开发中，敬请期待。