mcpField
S
seo-google

seo-google

github.com/infrasity-labs营销与增长15088 次安装18 周前更新
代码仓库

关于 seo-google

用于调用 Google SEO API 的技能，覆盖性能、索引、流量、关键词、视频和 NLP 数据。它按凭据级别确定可用命令，并可根据采集的数据生成报告。

主要功能

  1. 01查询 PageSpeed 与 CrUX 指标
  2. 02检查 Search Console 和索引数据
  3. 03获取 GA4 流量报告
  4. 04研究关键词与 YouTube 视频
  5. 05使用 Google NLP 分析文本
  6. 06生成 PDF 或 HTML 报告

适用场景

  1. 01对比 Lighthouse 结果与 Chrome 实测指标
  2. 02检查 URL 索引和站点地图状态
  3. 03查找自然搜索查询与落地页
  4. 04查看关键词搜索量和视频结果

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/infrasity-labs/dev-gtm-claude-skills --skill seo-google

安装后在 Claude Code 中输入/seo-google确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

assets/templates/
cwv-audit-report.md
gsc-performance-report.md
indexation-status-report.md
references/
auth-setup.md
dma-consent-mode-v2.md
ga4-data-api.md
indexing-api.md
keyword-planner-api.md
nlp-api.md
pagespeed-crux-api.md
rate-limits-quotas.md
search-console-api.md
supplementary-apis.md
youtube-api.md

详细介绍

Google SEO API

直接访问 Google 自有的 SEO 数据。弥合基于爬取的分析（现有的 seo-skills 技能）与 Google 实时实地数据之间的差距：真实的 Chrome 用户指标、实际索引状态、搜索表现和自然流量。

所有 API 均免费。设置需要一个 Google Cloud 项目，并配备 API 密钥和/或服务账号——运行 /seo google setup 查看分步说明。

前置条件

执行任何命令前，请检查凭据：

python scripts/google_auth.py --check --json

配置文件：~/.config/seo-skills/google-api.json

{
  "service_account_path": "/path/to/service_account.json",
  "api_key": "AIzaSy...",
  "default_property": "sc-domain:example.com",
  "ga4_property_id": "properties/123456789"
}

如果文件缺失，请阅读 references/auth-setup.md 并引导用户完成设置。

凭据等级
等级检测方式可用命令
0（API 密钥）存在 api_keypagespeed、crux、crux-history、youtube、nlp
1（OAuth/SA）+ OAuth 令牌或服务账号等级 0 + gsc、inspect、sitemaps、index
2（完整）+ 已配置 ga4_property_id等级 1 + ga4、ga4-pages
3（Ads）+ ads_developer_token + ads_customer_id等级 2 + keywords、volume

运行命令前，务必告知检测到的等级。

快速参考

命令功能等级
/seo google setup检查/配置 API 凭据--
/seo google pagespeed <url>PSI Lighthouse + CrUX 实地数据0
/seo google crux <url>仅 CrUX 实地数据（p75 指标）0
/seo google crux-history <url>25 周 CWV 趋势分析0
/seo google gsc <property>Search Console：点击次数、展示次数、CTR、排名1
/seo google inspect <url>URL 检查：索引状态、规范网址、爬取信息1
/seo google inspect-batch <file>从文件批量检查 URL1
/seo google sitemaps <property>GSC 站点地图状态1
/seo google index <url>向 Indexing API 提交 URL1
/seo google index-batch <file>批量提交最多 200 个 URL1
/seo google ga4 [property-id]GA4 自然流量报告2
/seo google ga4-pages [property-id]自然流量排名靠前的落地页2
/seo google youtube <query>YouTube 视频搜索（观看次数、点赞数、时长）0
/seo google youtube-video <id>YouTube 视频详情 + 热门评论0
/seo google nlp <url-or-text>NLP 实体提取 + 情感分析 + 分类0
/seo google entities <url-or-text>仅实体分析（用于 E-E-A-T）0
/seo google keywords <seed>通过 Google Ads Keyword Planner 获取关键词建议3
/seo google volume <keywords>通过 Keyword Planner 查询搜索量3
/seo google entity <query>Knowledge Graph 实体检查0
/seo google safety <url>Web Risk URL 安全检查0
/seo google quotas显示所有 API 的速率限制--

PageSpeed + CrUX

/seo google pagespeed <url>

结合 Lighthouse 实验室数据和 CrUX 实地数据。

脚本： python scripts/pagespeed_check.py <url> --json 参考： references/pagespeed-crux-api.md 默认设置： 同时采用移动设备和桌面设备策略，涵盖所有 Lighthouse 类别。

输出将实验室评分（某一时点的 Lighthouse 数据）与实地数据（28 天 Chrome 用户指标）合并。CrUX 会优先尝试 URL 级数据，失败时改用来源级数据。

/seo google crux <url>

仅 CrUX 实地数据（不运行 Lighthouse）。速度更快。

脚本： python scripts/pagespeed_check.py <url> --crux-only --json

/seo google crux-history <url>

25 周 CrUX History 趋势。显示 CWV 指标是在改善、保持稳定还是恶化。

脚本： python scripts/crux_history.py <url> --json 参考： references/pagespeed-crux-api.md

输出包含每项指标的趋势方向、变化百分比和每周 p75 值。

Search Console

/seo google gsc <property>

搜索分析：过去 28 天的点击次数、展示次数、点击率和排名。

脚本： python scripts/gsc_query.py --property <property> --json 参考： references/search-console-api.md 默认值： 28 天，维度=query,page，类型=web，限制=1000。

包含快速获胜机会检测：排名在 4–10 位且展示次数较高的查询。

/seo google inspect <url>

URL 检查：Google 提供的实际索引状态。

脚本： python scripts/gsc_inspect.py <url> --json

返回：判定结果（PASS/FAIL）、覆盖状态、robots.txt 状态、索引状态、 页面抓取状态、规范网址选择、移动设备易用性、富媒体搜索结果。

/seo google inspect-batch <file>

从文件中批量检查（每行一个 URL）。每个站点每天限 2,000 次。

脚本： python scripts/gsc_inspect.py --batch <file> --json

/seo google sitemaps <property>

列出已提交的网站地图及其状态、错误和警告。

脚本： python scripts/gsc_query.py sitemaps --property <property> --json

索引 API

/seo google index <url>

通知 Google 某个 URL 已更新。

脚本： python scripts/indexing_notify.py <url> --json 参考： references/indexing-api.md

索引 API 官方仅适用于 JobPosting 和 BroadcastEvent/VideoObject 页面。务必告知用户此限制。每日配额：200 次发布请求。

/seo google index-batch <file>

从文件中批量提交 URL。跟踪配额使用情况。

脚本： python scripts/indexing_notify.py --batch <file> --json

GA4 流量

/seo google ga4 [property-id]

自然流量报告：每日会话数、用户数、页面浏览量、跳出率和互动情况。

脚本： python scripts/ga4_report.py --property <id> --json 参考： references/ga4-data-api.md 默认值： 28 天，按自然搜索渠道组筛选。

/seo google ga4-pages [property-id]

按会话数排序的热门自然流量落地页。

脚本： python scripts/ga4_report.py --property <id> --report top-pages --json

YouTube（视频 SEO）

YouTube 提及与 AI 可见度的相关性最高（0.737）。免费，仅需 API 密钥。

/seo google youtube <query>

在 YouTube 上搜索视频。返回标题、频道、观看次数、点赞数和时长。

脚本： python scripts/youtube_search.py search "<query>" --json 参考： references/youtube-api.md 配额： 每次搜索 100 单位（免费额度为每天 10,000 单位）。

/seo google youtube-video <video_id>

视频详细信息、标签及热门 10 条评论。

脚本： python scripts/youtube_search.py video <video_id> --json 配额： 2 单位（视频详情 + 评论）。

NLP 内容分析

Google 自带的实体/情感分析。提升 E-E-A-T 评分。

/seo google nlp <url-or-text>

完整 NLP 分析：实体、情感和内容分类。

脚本： python scripts/nlp_analyze.py --url <url> --json 或 --text "..." 参考： references/nlp-api.md 免费额度： 每月 5,000 单位。需要在 GCP 项目中启用结算。

/seo google entities <url-or-text>

仅提取实体（速度更快，消耗的配额更少）。

脚本： python scripts/nlp_analyze.py --url <url> --features entities --json

关键词研究（Google Ads）

黄金标准的关键词搜索量数据。需要 Google Ads 账号。

/seo google keywords <seed>

根据种子词生成关键词创意。

脚本： python scripts/keyword_planner.py ideas "<seed>" --json 参考： references/keyword-planner-api.md 需要： 配置中的 Ads 开发者令牌 + 客户 ID（第 3 级）。

/seo google volume <keywords>

查询指定关键词的搜索量（以逗号分隔）。

脚本： python scripts/keyword_planner.py volume "<kw1>,<kw2>" --json

补充功能

/seo google entity <query>

检查知识图谱实体。验证品牌是否存在。

参考： references/supplementary-apis.md 使用带 API 密钥的 Knowledge Graph Search API。

/seo google safety <url>

通过 Web Risk API 检查恶意软件／社交工程标记。

参考： references/supplementary-apis.md

/seo google quotas

显示速率限制表。请阅读 references/rate-limits-quotas.md。

报告

执行任何分析命令后，询问用户是否要生成 PDF/HTML 报告。

/seo google report <type>

生成包含图表和分析数据的专业 PDF 报告。

脚本： python scripts/google_report.py --type <type> --data <json> --domain <domain> --format pdf

类型输入输出
cwv-auditPSI + CrUX + CrUX History 数据包含仪表盘、时间线和分布图的 Core Web Vitals 审计
gsc-performanceGSC 查询数据包含查询表格和快速见效建议的 Search Console 报告
indexation批量检查数据包含覆盖率环形图的索引状态
full所有数据的汇总全面的 Google SEO 报告（包含所有部分）

工作流：

  1. 运行数据收集命令（pagespeed、gsc、inspect-batch 等）
  2. 将 JSON 输出保存到文件：python scripts/pagespeed_check.py <url> --json > data.json
  3. 生成报告：python scripts/google_report.py --type cwv-audit --data data.json --domain <domain>

约定： 完成分析后，建议：“生成报告？使用 /seo google report <type>”

速率限制

API每分钟每天身份验证
PSI v5240 QPM25,000 QPDAPI Key
CrUX + History150 QPM（共享）UnlimitedAPI Key
GSC Search Analytics1,200 QPM/site30M QPDService Account
GSC URL Inspection600 QPM2,000 QPD/siteService Account
Indexing API380 RPM200 publish/dayService Account
GA4 Data API10 concurrent~25K tokens/dayService Account

跨技能集成

  • seo-audit：调用 seo-google Agent 获取实时 CWV 和索引数据（有条件时）
  • seo-technical：使用 pagespeed_check.py 获取真实 CWV 字段数据
  • seo-performance：CrUX 字段数据补充 Lighthouse 实验室数据
  • seo-sitemap：GSC 站点地图状态显示实际抓取／索引覆盖率
  • seo-content：GSC 查询数据为关键词定位提供依据
  • seo-geo：GSC 搜索外观数据包含 AI Overview 引用信息

输出格式

  • CWV 指标：使用红绿灯评级（良好／需要改进／较差）
  • 性能报告：使用带可排序列的表格
  • 始终注明数据新鲜度
  • 将报告保存为 GOOGLE-API-REPORT-{domain}.md
  • 使用 assets/templates/ 中的模板生成结构化输出

技术说明

  • INP 于 2024 年 3 月 12 日取代 FID。绝不要提及 FID。
  • CrUX 中的 CLS 值以字符串编码（例如，“0.05”）。脚本会处理解析。
  • CrUX 返回 404 表示流量不足，而非身份验证错误。
  • Search Analytics 数据有 2–3 天延迟。
  • round_trip_time 于 2025 年 2 月取代 CrUX 中的 effectiveConnectionType。
  • Custom Search JSON API 已不再向新客户开放（2025 年）。

错误处理

情况操作
未配置凭据运行 /seo google setup。列出只需 API key 即可使用的 Tier 0 命令。
服务账号没有 GSC 访问权限报告错误。说明如何将 client_email 添加到 GSC > Settings > Users > Add。
CrUX 数据不可用（404）报告 Chrome 流量不足。建议使用 PSI 实验室数据作为备用方案。
未找到 GA4 媒体资源报告错误。说明如何在 GA4 Admin > Property Details 中查找媒体资源 ID。
超出 Indexing API 配额报告每天 200 次的限制。建议优先处理最重要的网址。
速率限制（429）等待后使用指数退避重试。报告触发限制的 API。

评论

支持 Markdown