seo-webmaster-mcp

SEO Webmaster MCP

只需粘贴网址，即可通过助手审计网站。这个本地只读 MCP 可检测技术问题，并提供带有证据和验证步骤的建议。你可以连接 Google Search Console 和 Bing Webmaster Tools，以添加官方数据。需要 Node.js 22 或更高版本。

粘贴网址 → 找出具体问题 → 修复问题 → 再次运行审计以验证更改。

分步指南，包含一个 CTR 偏低的真实案例：如何使用 AI 助手和 Search Console 审计网站 SEO。

快速开始

首次审计无需克隆或编译仓库，也无需配置凭据。连接你的 MCP 客户端：

npx -y seo-webmaster-mcp 通过 stdio 启动服务。运行 npx -y seo-webmaster-mcp config codex|claude|cursor 以复制相应配置；不要在其中填写密钥。

Codex：

codex mcp add seo-webmaster -- npx -y seo-webmaster-mcp
codex mcp list

**Claude Desktop：**将以下内容添加到 claude_desktop_config.json 并重启应用。**Cursor：**将同一个对象添加到 mcp.json。

{
  "mcpServers": {
    "seo-webmaster": {
      "command": "npx",
      "args": ["-y", "seo-webmaster-mcp"]
    }
  }
}

如果你的客户端需要其他路径，请参阅 Codex MCP 配置、Claude Desktop 帮助或 Cursor MCP 文档。在 Windows 上，如果客户端找不到 npx，请使用可执行文件 npx.cmd 的绝对路径。

首次审计

请助手执行以下操作：

使用 seo_audit_advanced 审计 https://example.com。优先处理发现的问题，并列出受影响的网址、证据、修复方法以及如何验证每项修复。区分已确认的问题和需要结合上下文检查的项目。

最简调用如下：

{ "baseUrl": "https://example.com/" }

报告可能会检测 HTTP 错误、内部断链、缺失或重复标题、格式错误的规范网址以及索引指令。报告还会建议检查缺少 alt 的图片、页面语言和 viewport。该工具会分析收到的 HTML，不会执行 JavaScript，也不会确认实际索引状态。指定 Google 或 Bing 属性之前，官方数据部分将为空。

summary 会说明分析了多少个 HTML 页面、检查了什么、哪些项目仍待处理，以及抓取是否受到限制。actions: [] 表示在这些检查和样本中未检测到问题；这不等于完成了全面审计，也不保证没有可改进之处。

summary.truncationReasons 会说明达到的限制：max_pages（待处理网址）、discovery_limit（发现的不同网址最多为 2 × maxPages）或 sitemap_limit（最多六个 sitemap 文件）。重复链接和 #seccion 之类的片段不会额外占用页面额度。如果存在第一个 <base href>，则会使用它解析规范网址和相对链接。

每个页面都包含 jsonLdBlocks，其中的 application/ld+json 块从 1 开始编号。parsed 表示 JSON 可读取，且根节点为对象或对象数组；invalid_json 表示 JSON 格式错误或为空，invalid_root 表示根节点不兼容。出现错误时会生成 invalid_json_ld 操作，其中包含网址、代码块和修复步骤。此检查不会解析远程上下文，也不会验证 schema.org 语义或富媒体搜索结果要求；请使用 Rich Results Test 完成此项检查。indexablePages 和 snippetEligiblePages 是根据观察到的 HTML 得出的信号，不代表实际已编入索引或符合条件。

如需快速检查单个页面，请添加 "maxPages": 1。默认最多抓取 100 个页面。

0.4.0 中新增的 HTML 检查

操作	检查内容	解读方式
images_missing_alt	body 中缺少 alt 属性的图片。	逐张检查图片：有信息的图片应使用描述性文本，装饰性图片应使用 alt=""。审计接受空 alt，但不评估文本质量。
missing_lang	<html lang> 缺失或为空。	声明实际语言，以帮助屏幕阅读器和其他辅助技术；这不代表已测量的 SEO 惩罚。
missing_viewport	head 中缺少 meta viewport，或其内容为空。	检查移动端配置。存在该标签并不能证明布局在移动端正常运行。
invalid_canonical	规范链接的 href 无法解析为有效的 HTTP(S) URL。	修正该值，并确认它对应所选版本。页面的其余分析结果会保留。

前三个操作的优先级较低，且 confidence: "inferred"：证据是观察到的缺失，修正方式需要结合上下文判断。每个操作都包含 URL、证据、步骤和验证方法。系统会统计所有受影响的页面，并显示最多二十个示例 URL。

每个页面都会包含 lang 和 viewport（观察到的值或 null）、canonicalError（null 或错误原因）以及 images：

{
  "total": 2,
  "missingAlt": 1,
  "examples": [{ "imageIndex": 1, "src": "./audit-flow.svg" }]
}

imageIndex 是图片在 body 的 img 元素中的位置，从 1 开始。每页的 examples 最多包含五张缺少 alt 的图片；src 保留收到的属性值，截断至 300 个字符；如果缺失则为 null。这些检查不会下载图片，也不会额外发送请求。这不是完整的无障碍审计。

noindex 和 snippetBlocked 信号会综合一般的 robots 标签、所有 googlebot 标签，以及适用于 Googlebot 的 HTTP 规则。系统会将 none 识别为 noindex, nofollow，且不会把仅针对其他 Agent 的规则归因于 Google。这些信号仅针对 Google，并非对所有搜索引擎的模拟。规范链接无效时，canonical 会设为 null 并生成 invalid_canonical，不会重复生成 missing_canonical，也不会将 HTTP 200 转换为连接错误。

演示：检测、修复和验证

在仓库检出目录中，执行 npm ci 后运行：

npm run demo

此演示会在模拟 DNS 和 HTTP 的环境中执行两次真实的 MCP 调用，不会访问互联网，也不会查询凭据。使用原始文件 before.html 和 after.html：

运行阶段	预期结果
修复前	invalid_canonical、images_missing_alt、missing_lang 和 missing_viewport。保留 HTTP 200。
修复后	四项操作均消失；两张图片都有 alt，包括一张带有 alt="" 的装饰性图片。

输出内容包括覆盖范围、页面数据和操作的完整证据。audit.example 是演示中的虚构目标。要对网站重复此演示，请将文件托管在你拥有或获授权使用的公开 URL 上，并使用 maxPages: 1 审计每个 URL；如果更改了 after.html 的路径，请相应调整其规范 URL。本示例中没有操作，并不保证页面会被编入索引或获得相应排名。

对于你拥有或获授权使用的网站，请使用一个没有 <title> 的公开测试页面。使用 maxPages: 1 对其进行审计：missing_title 操作会包含该页面的 URL 和受影响的页面数。添加描述性标题，发布修复，然后重复同一项审计：该操作应该会消失。你可以展示两次运行的结果来记录改进；此项更改并不保证排名结果。

你还可以通过 <script type="application/ld+json">{"@type":"Organization",}</script> 重现 JSON-LD 错误：末尾的逗号会导致 invalid_json_ld。删除逗号并重复审计后，该区块应该显示为 parsed，相应操作也会消失。

它是否帮你发现了并修复的问题？你在哪一步遇到了困难？在 issue 中告诉我们，并注明你的 MCP 客户端、操作系统和复现步骤。请将私人数据匿名化，并避免包含凭据。

保存和比较审计结果（0.5.0）

你可以直接通过 CLI 完成整个流程，无需克隆仓库：

npx -y [email protected] audit https://example.com/ --max-pages 25 --save
npx -y [email protected] history
npx -y [email protected] report ID --format markdown --out informe.md
# Tras corregir y publicar tu web, repite audit con --save:
npx -y [email protected] compare ID_BASE ID_ACTUAL --format markdown

--save 会将报告显式保存到本地配置文件，并返回 saved.id。不使用该选项则不会创建历史记录。比较结果会区分 新增、持续存在、已解决和无法比较的问题：跳过页面 或检查失败，绝不会被视为已修复。--out 可导出 JSON 或 Markdown，且不会覆盖现有文件。

你可以通过 MCP 使用 seo_audit_save、seo_audit_history、seo_audit_report 和 seo_audit_compare。29 个工具中，28 个声明为读取操作； seo_audit_save 声明为非幂等的本地写入操作。没有任何工具会修改网站。

新版本增加了隔离模块，提供 hreflang 覆盖率和检查，以及对多个 canonical URL／目标地址、站点地图一致性、标头、社交卡片和所选 schema.org 类型属性（包括 @graph）的检查。 --render js 可启用已安装的 Chrome/Chromium/Edge，--performance 可查询 PageSpeed Insights；两者均为可选项。这并非完整的语义验证。

npx -y [email protected] audit https://example.com/ --render js --max-pages 5 --save
npx -y [email protected] audit https://example.com/ --performance --performance-strategy mobile

请参阅用法、工具和限制、验证证据和路线图。

添加 Google 或 Bing（可选）

配置你想使用的每个提供商：

npx -y seo-webmaster-mcp setup bing
npx -y seo-webmaster-mcp setup google --client /ruta/al/cliente-oauth.json
npx -y seo-webmaster-mcp status
npx -y seo-webmaster-mcp doctor

**Bing：**在 Bing Webmaster Tools 中创建密钥。设置助手会在不显示密钥的情况下请求输入，并检查密钥是否有效。

--help 会显示命令，--version 会显示已安装的版本。如果已配置的提供商出现故障，doctor 会返回退出代码 1；如果没有提供商，则返回 not_configured 和代码 0。

**Google：**在 Google Cloud Console 中启用 Search Console API，配置 OAuth 同意屏幕，并下载 Desktop app 类型的 OAuth 客户端。如果应用处于 Testing 模式，请将你的账号添加为测试用户。将 JSON 文件传递给 setup google 命令；浏览器会请求只读访问权限，并通过本地回调完成连接。每位用户都应创建自己的 OAuth 客户端；请勿共享 JSON 文件或刷新令牌。官方授权指南。

配置保存在仓库之外的用户配置文件中。status 会显示路径和状态，但不会泄露机密；doctor 会测试对两个提供商的实际访问权限。若要断开连接，请运行：npx -y seo-webmaster-mcp disconnect google 或 disconnect bing。在 macOS/Linux 上，文件权限为 0600；在 Windows 上，文件保存在用户的 AppData 中。请保护你的系统会话，因为刷新令牌会保存在本地。

使用官方数据进行审计

请你的 MCP 客户端调用 seo_audit_advanced：

{
  "gscSiteUrl": "sc-domain:example.com",
  "bingSiteUrl": "https://example.com/",
  "baseUrl": "https://www.example.com/",
  "maxPages": 100
}

两个属性都是可选的：指定一个或两个属性即可添加官方数据，也可以省略它们，仅按 URL 进行审计。如果省略日期，提供商数据将使用截至执行前三天的最近 90 个完整日的数据。爬取从指定 URL 开始，遵循站点地图和内部链接，遵守 SEO-Webmaster-MCP 的 robots.txt 规则，并仅限于同一主机的公开 URL（包括 www 变体）。系统还会检查重定向中的 robots 规则以及每个来源的规则；如果 robots 检查遇到网络故障、HTTP 429 或 5xx，该来源的爬取将停止，并报告错误。系统可识别共享组、通配符、Allow 和 Disallow。

DNS 解析和请求的超时时间均为十秒；连接使用已验证的公共地址。下载期间，每个响应的大小限制为 2 MB。达到 maxPages（最多 500）后，爬取即结束。报告包含可用数据、技术问题、GEO 信号，以及附有验证步骤的优先操作建议。部分失败不会影响报告其余内容，并会显示错误。

原有的 seo_audit_site 工具仍可使用。新增的官方工具包括 gsc_query_advanced、gsc_sitemap_details、bing_feed_details、bing_page_queries 和 bing_query_pages。现有工具不会更名。

导入 Google 生成式功能的展示次数

Search Console 支持导出生成式效果报告。该视图无法通过公共 API 作为独立资源获取。按网页或日期导出 CSV 表格，然后运行：

npx -y seo-webmaster-mcp geo-import reporte.csv sc-domain:example.com 2026-07-01 2026-09-24 page

按日期生成表格时，使用 date 而不是 page。支持以下表头：Page/Página、Date/Fecha 和 Impressions/Impresiones。CSV 必须包含这些列组成的表格，且最多包含 10 000 行。导入数据会保存在本地配置中，并按资源分别存储。geo_report_summary 和 seo_audit_advanced 会单独显示导入的数据。这些是 Google 生成式功能的展示次数，不是 ChatGPT、Claude 或其他系统中的引用量。

展示次数必须是非负整数。标记 ~ 和 - 会保留为 null，并通过 unknownImpressionRows 标明未知行数；如果这些标记影响日期，totalImpressions 会设为 null。空指标、分数以及无效或超出声明时段的日期都会被拒绝。如果某个 CSV 曾由旧版本导入，且旧版本将这些标记转换成了零，请重新导入以恢复这种区分。

开发

npm install
npm test
npm run verify:package
npm pack --dry-run

软件包包含 dist、README、变更日志和许可证。示例和发布准备工作保留在代码仓库中。请勿发布凭据或 OAuth 客户端。官方数据可能不完整或有所延迟；MCP 会区分无数据和流量为零，并避免将启发式判断呈现为已确认的错误。

verify:package 会打包项目并将 tarball 安装到临时目录，检查可执行文件及其 29 个 MCP 工具，然后使用刻意设为无效的本地凭据再次运行演示。安装需要访问 npm 注册表；测试审核使用模拟的 DNS/HTTP。该流程也会在 CI 中针对 Linux、Windows 和 macOS 执行。

抓取和 HTTP 连接分别使用 robots-parser 和 Undici。它们不会增加密钥或外部服务。

开发参考资料：claude-seo-ai，尤其是其图像和视口检查、模块化组织以及报告比较（MIT）；Google robots 指令、文档语言、装饰性图像和 Lighthouse 视口。此版本的实现和示例均为原创；未纳入第三方文件。

---

English 快速开始

分步指南（西班牙语），包含一个真实的低 CTR 案例：Cómo auditar el SEO de tu web con tu asistente de IA y Search Console。

安装 Node.js 22+，然后连接你的 MCP 客户端。首次审核只需一个公开 URL：

codex mcp add seo-webmaster -- npx -y seo-webmaster-mcp

对于 Claude Desktop 或 Cursor，请使用上方的 mcpServers JSON。运行 npx -y seo-webmaster-mcp config claude 或 config cursor 来打印配置。让你的助手调用 seo_audit_advanced，并传入 { "baseUrl": "https://example.com/" }，然后说明证据、受影响的 URL、修复方法和验证步骤。抓取会分析收到的 HTML，但不会执行 JavaScript，也不会确认页面是否已被搜索引擎收录。检查单个页面时，添加 maxPages: 1。 summary 报告覆盖范围、已执行的检查和未执行的检查。空的 actions 数组表示在已抓取的样本中，这些检查未发现问题。每个页面都会通过 jsonLdBlocks 展示 JSON-LD 区块，其中包含从 1 开始的脚本索引，以及 parsed、invalid_json 或 invalid_root 状态。语法错误或根节点错误会生成 invalid_json_ld；parsed 并不代表已确认符合 schema.org 语义或具备富媒体搜索结果资格。后者请使用 Rich Results Test 检查。就绪度计数描述的是观察到的 HTML 信号，并不代表已确认被编入索引或可见于 AI。

0.4.0 版本还会报告缺少 alt 的图片、缺失或为空的 HTML 语言和视口声明，以及格式错误的规范 URL。每个页面会展示 lang、viewport、canonicalError 和 images（total、missingAlt、最多五个示例，包含从 1 开始的 imageIndex 和原始 src，上限为 300 个字符）。装饰性图片的空 alt="" 会被接受。这些是静态 HTML 检查；语言准确性、替代文本质量和响应式布局仍需人工审核。Robots 标记会合并通用指令和针对 Googlebot 的规则，但不包括其他 Agent 的定向规则。

0.5.0 版本新增明确的审计历史记录、JSON/Markdown 导出、比较、hreflang、选定的 schema 属性、社交元数据检查和内部链接图。运行 npx -y seo-webmaster-mcp audit URL --save，然后运行 report ID 或 compare BASELINE_ID CURRENT_ID。对于被省略的页面和未通过的检查，绝不会将其标记为已解决的问题。

可选的 --render js 会使用已安装的 Chrome/Chromium/Edge，并采用隔离配置文件和经过验证的资源传输；不会自动下载浏览器。可选的 --performance 会将入口 URL 发送到 Google PageSpeed Insights API。可通过环境变量提供 PAGESPEED_API_KEY。实验室数据和实测数据会分开报告；缺失的实测数据会保持未知。请参阅用法和限制。

爬虫本身会为 SEO-Webmaster-MCP 遵循 robots.txt，包括共享组、通配符和重定向。无法获取 robots 响应（网络错误、429 或 5xx）时，会停止抓取该源站。DNS 地址会经过验证并固定到连接，响应正文在流式传输时上限为 2 MB。summary.truncationReasons 会列出页面、URL 发现和站点地图的限制。相对链接会遵循文档的基础 URL。导入的 GEO 标记 ~ 和 - 会保留为未知值（null），而不是零展示次数。

维护者可以运行 npm run verify:package，将实际 tarball 安装到临时目录，并验证其二进制文件、版本、MCP 工具以及修复前后的审计结果。安装时需要访问 npm 注册表。--help 和 --version 无需连接服务提供方即可运行；配置的服务提供方发生故障时，doctor 会以代码 1 退出。

如需可复现的离线修复前后演示，请克隆仓库，运行 npm ci，然后运行 npm run demo。该命令会使用仓库中附带的示例，通过模拟 DNS/HTTP 调用 MCP 服务：修复前有四个问题，修复后为零，并提供证据和覆盖范围。要在 MCP 客户端中本地测试更改，请运行 npm run build，并将服务命令指向 node /absolute/path/to/seo-webmaster-mcp/dist/cli.js；重新构建后请重启服务。npx -y seo-webmaster-mcp 会运行已发布的软件包。

可选运行 npx -y seo-webmaster-mcp setup bing 或 npx -y seo-webmaster-mcp setup google --client /path/to/desktop-oauth-client.json，然后在审计中提供 bingSiteUrl 或 gscSiteUrl，以纳入官方数据。审计为只读；其行动计划会分别指出已确认的问题和推断出的机会。可使用 geo-import 从 Search Console CSV 导出文件导入 Google 生成式搜索展示次数。 这次审计是否帮你解决了问题？你卡在哪一步？请分享反馈，并注明你使用的 MCP 客户端和操作系统，同时省略凭据和私人数据。