claude-seo 的 MCP 集成实战：打通 PageSpeed、Search Console 与 DataForSEO 实时 SEO 数据管道

Model Context Protocol（MCP）让 claude-seo 这个通用 SEO 技能包具备了调用外部 API、获取真实线上数据的能力：从 Google PageSpeed Insights 与 CrUX 的 Core Web Vitals 现场数据，到 Search Console 的搜索表现，再到 DataForSEO 的 SERP、关键词、外链与 GEO/AI 可见性数据。读完本文，你将掌握在 claude-seo 中配置这些 MCP 服务器、用 curl/Python 直接调用 Google 免费 API、并通过官方扩展接入生产级 SEO 数据服务的完整方案。

一、为什么需要 MCP：从静态分析到实时数据

claude-seo 的本地子技能（技术 SEO、内容、外链、Schema 等）默认基于 HTML 源码和静态规则做分析，而 MCP 集成打开了一扇通往外部真实世界的门：claude-seo 可以通过 Model Context Protocol 服务器访问外部 API，从而增强分析能力（见 docs/MCP-INTEGRATION.md）。

从仓库源码结构看，这种集成是"分层"的：

• 直接 HTTP 调用层：不需要 MCP 服务器，靠 Python 脚本直连 Google 免费 API（PageSpeed Insights v5、CrUX）；
• MCP Server 层：通过~/.claude/settings.json注册mcpServers，让 Claude Code 原生感知工具，如mcp-server-gsc、mcp-server-pagespeed；
• 官方扩展层：仓库内预置的 DataForSEO 扩展 等，由安装脚本自动完成 MCP 配置。

二、Google 免费 API：PageSpeed Insights 与 CrUX

2.1 凭据准备

PageSpeed Insights（PSI）与 Chrome UX Report（CrUX）API 是免费且无需 OAuth 的，只需要一个 Google API Key。配置步骤：

1. 在 Google Cloud Console 创建项目；
2. 在 API Library 中启用PageSpeed Insights API与Chrome UX Report API；
3. 在 Credentials 中创建 API Key（建议限制仅用于上述两个 API）。

claude-seo 提供了一站式凭据管理脚本 scripts/google_auth.py，支持多种方式：

• 环境变量：GOOGLE_API_KEY
• 配置文件：~/.config/claude-seo/google-api.json中的api_key字段
• 校验命令：python scripts/google_auth.py --check psi，它会按服务区分认证方式（PSI/CrUX 用 api_key，GSC/Indexing/GA4 用 OAuth 或服务账号）

源码中定义的标准请求头是X-Goog-Api-Key（见 scripts/google_auth.py 的google_api_key_headers()），这也是文档中 curl 示例使用的头部。

2.2 直接调用示例（curl）

文档给出了最直接的验证方式——用 curl 测试 PSI API：

curl -H "X-Goog-Api-Key: $GOOGLE_API_KEY" \ "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=URL"

执行后会返回包含 Lighthouse 评分、实验室指标、机会项（opportunities）等内容的 JSON。可将strategy参数设为mobile或desktop分别测试移动端与桌面端。

2.3 Python 方式：仓库内置的组合检查器

仓库提供了比文档示例更完整的工程化实现：scripts/pagespeed_check.py 是一个"PSI + CrUX 组合检查器"，把实验室数据与现场数据合并成一份报告。核心端点常量与文档一致：

• PSI_ENDPOINT = "https://www.googleapis.com/pagespeedonline/v5/runPagespeed"
• CRUX_ENDPOINT = "https://chromeuxreport.googleapis.com/v1/records:queryRecord"

典型用法：

# 默认同时跑 PSI（mobile + desktop）与 CrUX 现场数据 python scripts/pagespeed_check.py https://example.com # 只看现场数据（必须有 API Key） python scripts/pagespeed_check.py https://example.com --crux-only # 只看 Lighthouse 实验室数据，JSON 输出 python scripts/pagespeed_check.py https://example.com --psi-only --json

脚本还内置了Core Web Vitals 阈值表（good/poor 判定）：

其中 CLS 在 CrUX 返回中是以字符串编码的，脚本做了显式的浮点解析处理（见 scripts/pagespeed_check.py），这是直接拼装请求时常踩的坑。

文档给出的最小 Python 示例同样可直接复用：

import requests def get_pagespeed_data(url: str, api_key: str) -> dict: """Fetch PageSpeed Insights data for a URL.""" endpoint = "https://www.googleapis.com/pagespeedonline/v5/runPagespeed" params = { "url": url, "strategy": "mobile", # or "desktop" "category": ["performance", "accessibility", "best-practices", "seo"] } headers = {"X-Goog-Api-Key": api_key} response = requests.get(endpoint, params=params, headers=headers) return response.json()

CrUX 现场数据使用 POST 查询queryRecord：

def get_crux_data(url: str, api_key: str) -> dict: """Fetch Chrome UX Report data for a URL.""" endpoint = "https://chromeuxreport.googleapis.com/v1/records:queryRecord" payload = { "url": url, "formFactor": "PHONE" # or "DESKTOP" } headers = {"Content-Type": "application/json", "X-Goog-Api-Key": api_key} response = requests.post(endpoint, json=payload, headers=headers) return response.json()

注意：仓库的 pagespeed_check.py 还演示了如何把目标区分为"URL 级"与"origin 级"查询，并在 URL 级无数据时自动回退到 origin 级；当目标站点 Chrome 流量不足时 CrUX 会返回 404，脚本会给出明确的"流量不足"提示。

2.4 可获得的核心指标

来自 PageSpeed Insights（实验室数据）：

来自 CrUX（现场数据，真实用户）：

三、通过 MCP Server 接入：Search Console 与 PageSpeed

3.1 Google Search Console（mcp-server-gsc）

需要有机搜索数据（search performance、URL 检测、站点地图管理）时，使用社区 MCP 服务器mcp-server-gsc。在~/.claude/settings.json中注册：

{ "mcpServers": { "google-search-console": { "command": "npx", "args": ["-y", "mcp-server-gsc"], "env": { "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json" } } } }

注意GOOGLE_CREDENTIALS_PATH指向的是service account 的 JSON 密钥文件。Search Console API 走 OAuth 或服务账号认证（见 scripts/google_auth.py 中gsc: oauth_or_sa的定义），且需要把服务账号的client_email添加到 Search Console 的"用户和权限"中。仓库的 scripts/gsc_query.py 与 scripts/gsc_inspect.py 是这类 API 的本地脚本化实现，可作对照参考。

3.2 PageSpeed Insights MCP Server（mcp-server-pagespeed）

需要以 MCP 工具方式获取 Lighthouse 审计、CWV 指标和性能评分时，使用社区 MCP 服务器mcp-server-pagespeed：

{ "mcpServers": { "pagespeed": { "command": "npx", "args": ["-y", "mcp-server-pagespeed"], "env": { "PAGESPEED_API_KEY": "your-api-key" } } } }

其底层调用的仍是 PSI v5 API，只是把请求封装成了 MCP 工具，供 Claude Code 在会话中直接调用。

3.3 手工注册的一般模式

综合仓库内多个 MCP 配置（如 extensions/dataforseo/install.sh 的配置片段），MCP 服务器统一注册在~/.claude/settings.json的mcpServers节点下，标准字段为：

• command：启动方式（通常是npx）；
• args：包名与参数（如["-y", "dataforseo-mcp-server"]）；
• env：该服务器所需的全部环境变量（API Key、凭据路径、模块开关等）。

安装脚本会以 0600 权限原子化写入该文件，避免凭据以明文落入日志或第三方进程。

四、2025-2026 生产级 SEO MCP 生态一览

MCP 生态在 SEO 领域已相当成熟，文档列出的生产可用集成如下：

仓库内已内置 Ahrefs 扩展：@ahrefs/mcp@0.0.11官方服务器，提供metrics、backlinks、organic、content等命令，并可与 seo-backlinks 技能的多源置信度加权配合使用（见 extensions/ahrefs/skills/seo-ahrefs/SKILL.md）。

五、DataForSEO 官方扩展：22 条命令的实时 SEO 数据层

DataForSEO 是文档中唯一带官方扩展的付费数据源，也是 claude-seo 实时数据能力的核心载体。

5.1 安装与自动配置

# Unix/macOS/Linux ./extensions/dataforseo/install.sh # Windows (PowerShell) .\extensions\dataforseo\install.ps1

安装脚本会依次完成：校验 Claude SEO 与 Node.js 20+ 环境 → 交互式收集 DataForSEO 用户名/密码 → 安装 skill 与 agent 文件 → 自动合并 MCP 配置到~/.claude/settings.json→ 预下载 npm 包（见 extensions/dataforseo/install.sh）。凭据通过 argv 传入内嵌 Python 脚本，以 0600 权限原子写入，不会泄露到 shell 历史。

如果自动配置失败，可参照 extensions/dataforseo/docs/DATAFORSEO-SETUP.md 手工添加：

{ "mcpServers": { "dataforseo": { "command": "npx", "args": ["-y", "dataforseo-mcp-server"], "env": { "DATAFORSEO_USERNAME": "your-email@example.com", "DATAFORSEO_PASSWORD": "your-api-password", "ENABLED_MODULES": "SERP,KEYWORDS_DATA,ONPAGE,DATAFORSEO_LABS,BACKLINKS,DOMAIN_ANALYTICS,BUSINESS_DATA,CONTENT_ANALYSIS,AI_OPTIMIZATION", "FIELD_CONFIG_PATH": "/home/youruser/.claude/skills/seo/dataforseo-field-config.json" } } } }

5.2 9 大模块与 22 条命令

DataForSEO 扩展启用了全部 9 个 API 模块（见 extensions/dataforseo/README.md）：

命令示例：

/seo dataforseo serp best coffee shops # Google 有机 SERP（可用 se 参数切 Bing/Yahoo） /seo dataforseo keywords seo tools # 关键词想法与建议 /seo dataforseo backlinks example.com # 完整外链画像（含垃圾分） /seo dataforseo intersection a.com b.com # 2-20 个域名的关键词/外链交集 /seo dataforseo ai-mentions your brand # 跨 LLM 平台的品牌提及追踪（GEO）

在 SERP 分析中，serp_google_images_live_advanced支持 Google Images 图片排名分析；site:/filetype:过滤符会产生5 倍 API 成本，使用前应提醒用户（见 extensions/dataforseo/skills/seo-dataforseo/SKILL.md）。

5.3 字段过滤：节省约 75% Token

扩展自带的 field-config.json 通过FIELD_CONFIG_PATH环境变量注入 MCP 服务器，只保留 SEO 相关字段（如 SERP 的title/url/domain/featured_snippet/ai_overview、backlinks 的spam_score/anchor等），把 API 响应体积压缩约 75%，既省钱又提速。

5.4 成本护栏：先估算、再调用、后记账

DataForSEO 按调用计费，仓库为此实现了成本治理脚本 scripts/dataforseo_costs.py：

# 调用前估算成本，返回 approved / needs_approval / blocked python3 scripts/dataforseo_costs.py check <endpoint> [--count N] # 调用后记账 python3 scripts/dataforseo_costs.py log <endpoint> <actual_cost> # 查看今日/近 7 日支出 /seo dataforseo costs today /seo dataforseo costs summary

典型成本参考（标准队列，美元/次）：SERP 约 $0.001–0.003、关键词研究约 $0.0005–0.05、外链概要约 $0.002–0.02、页面级 on-page 分析约 $0.01–0.05、AI 优化约 $0.01。新账户通常带有免费试用额度。

5.5 与既有技能的联动

安装后，其他 claude-seo 子技能会自动感知 DataForSEO 可用性并使用实时数据：/seo audit用真实 SERP 与外链数据、/seo technical用 on-page 真实抓取、/seo content用关键词量/难度/意图、/seo geo用 ChatGPT 抓取与 LLM 提及、/seo plan用竞品与关键词数据（见 extensions/dataforseo/README.md）。输出时会标注"DataForSEO (live)"以区别于静态分析。

六、最佳实践

文档给出的四条核心实践，结合仓库源码可进一步落实为可操作规则：

1. Rate Limiting（限流）：尊重 API 配额——PageSpeed 通常为 25,000 次/天（源码中标注 240 QPM / 25,000 QPD，见 scripts/pagespeed_check.py）；CrUX 与 History API 共享 150 QPM。遇到 429 应等待后重试。
2. Caching（缓存）：缓存结果避免重复调用。DataForSEO 的 SKILL 文档同样要求"会话内缓存，不重复拉取同一数据"。
3. Field vs Lab（现场优先）：排名信号优先使用 CrUX 现场数据（真实用户第 75 百分位），实验室数据仅作诊断参考。仓库的组合检查器同时输出两者并给出评级，正是为了支持这种对比。
4. Error Handling（错误处理）：优雅处理 API 错误。仓库脚本对 400（参数错误）、429（限流）、404（CrUX 无数据）、超时（120s）均有语义化错误信息；DataForSEO 侧对 401（凭据错误）、402（余额不足）、429（每秒限流）也给出了明确处置建议。
5. 凭据安全：Google 侧使用X-Goog-Api-Key请求头而非 URL 参数，且 scripts/google_auth.py 提供了redact_google_api_key()在异常输出前抹除 Key；MCP 配置文件统一以 0600 权限写入。

七、没有 API Key 时的降级模式

如果没有任何 API Key，claude-seo 仍可完成有价值的静态分析：

1. 分析 HTML 源码以发现潜在问题
2. 识别常见性能问题
3. 检查阻塞渲染的资源（render-blocking resources）
4. 评估图片优化机会
5. 检测 JavaScript 过重实现

此时分析报告会明确注明：真正的 Core Web Vitals 测量需要来自真实用户的现场数据（field data），以此区分静态诊断与实测结果的边界。

八、总结

claude-seo 的 MCP 集成是一条从"免费 Google 数据 → 社区 MCP 服务器 → 官方付费扩展"的渐进式实时数据管道：零成本阶段可用 curl 或 pagespeed_check.py 获取 PSI/CrUX 数据；需要搜索表现数据时注册mcp-server-gsc；需要规模化、商业级的 SERP/关键词/外链/GEO 数据时，一键安装 DataForSEO 扩展 即可获得 9 大模块、79 个工具、22 条命令，配合字段过滤与成本护栏，让每一次 SEO 分析都建立在真实、可溯源的数据之上。