seo-audit-mcp

一个 MCP 服务器，让 Claude（或任何 MCP 客户端）能够审计在线网站的技术 SEO：站点地图覆盖、每个页面上的问题以及重定向链。

用日常语言提问 — "审计 mortgagecalculatortools.com，并告诉我哪些页面 Google 从未被告知" — 模型就会调用工具、爬取网站，并用具体细节作答。

它解决的问题

网站的 sitemap.xml 是你告诉 Google 哪些页面存在的方式。当某个页面缺失时，不会有报错，也不会有警告——该页面只是永远无法积累展示。手动检查意味着要将文件系统列表与 XML 文件进行对比，因此实际上没有人会这么做。

案例研究：一个 25 页的缺口，结果证明是正确的

最初指向的这个网站在磁盘上有 125 个 HTML 文件，其 sitemap 中有 100 个 URL。一个 25 页的缺口——这种发现通常会被当作 bug 记录下来并分配给某人。

一次 sitemap_coverage 调用暴露了这个缺口，对样本进行的 audit_urls 调用解释了原因：这 25 个页面全都带有 <meta name=\"robots\" content=\"noindex, follow\">。它们是两个刻意取消索引的内容集群，sitemap 完全正确地省略了它们。随后对照文件系统验证：磁盘上有 25 个 noindex 页面，同样的 25 个在 sitemap 中缺席，零个 noindex 页面被错误包含。完全一致。

这才是最有用的结果。单独的覆盖数字（"125 对 100"）看起来像个缺陷，会白白消耗某人一天的时间；而覆盖情况加上逐页的 noindex 状态，则能在一分钟内结束讨论。这个工具在消除误报方面，与发现真实缺口一样有价值——这就是为什么 audit_urls 会逐页报告 noindex，而不是只统计 URL。

工具

每个工具都会返回结构化 JSON，其中包含每个页面的 issues 列表和聚合的 issue_summary，这样模型就可以基于计数进行推理，而无需重新阅读原始 HTML。

安装

pip install -e .

需要 Python 3.10+。依赖：mcp>=2.0.0、httpx。

连接到 Claude Code

在你的项目中添加到 .mcp.json（或 ~/.claude.json 用于全局使用）：

{
  "mcpServers": {
    "seo-audit": {
      "command": "python",
      "args": ["-m", "seo_audit_mcp"]
    }
  }
}

对于 Claude Desktop，同一内容块放在 claude_desktop_config.json 中。

然后直接提问：

获取 https://example.com/sitemap.xml 的 sitemap，审计前 20 个 URL，并按频率总结问题。

直接运行

python -m seo_audit_mcp        # stdio transport

设计说明

有三个值得特别指出的设计决策，因为它们是演示与实际指向客户生产环境的版本之间的区别：

爬虫在结构上就是限速的。 fetch_many 运行在一个上限为 16 个并发请求的 asyncio.Semaphore 之后，并且每个工具都会限制其输入。如果没有这个上限，一个 500 个 URL 的 sitemap 会一次打开 500 个 socket，看起来就像是对目标主机的攻击。爬取是由 目标 站点承担的成本，因此无法从工具层面向上配置这个上限。

没有一次抓取失败会中止整个运行。 fetch_one 捕获 httpx.HTTPError 并将其记录在返回的 PageAudit 上，而不是抛出异常。在 200 个 URL 的爬取中，一个死主机会使一行降级，而不会丢掉 199 个正确结果。

解析是故意宽松的。 现实中的 HTML 经常格式错误，以至于严格的解析器在爬取中途抛错是一个负担。提取器使用宽容的正则表达式，返回 None 而不是抛出——但陷阱已被处理：在计词和标题提取之前会剥离 <script> 和 <style> 主体，因此 JS 字符串字面量中的 <h1> 不会被计为标题，并且相对 canonical 会相对于页面 URL 进行解析。

normalize_url 故意 不 去除末尾斜杠：/a 和 /a/ 可能是完全不同的页面，而将它们折叠起来会掩盖这个工具要揭示的重复内容问题。

测试

pip install -e ".[dev]"
pytest

测试套件无需网络——HTTP 通过 httpx.MockTransport 进行模拟，因此它可以在 CI 和飞机上运行。它覆盖了生产中会踩坑的解析边界情况：脚本嵌入的标题、无命名空间的 sitemap、相对 canonical、返回带样式 HTML 404 但状态码为 200 的 sitemap URL，以及将非 HTML 内容类型错误报告为"缺少标题"的页面。

许可证

MIT