MCP SEO Auditor

MCP SEO Auditor

在 Claude Code 或 Cursor 中免费进行页面 SEO 审核——在页面上线前，找出标题错误、缺少元描述、规范链接问题、robots 冲突和 JSON-LD 错误。完全本地运行，无需 API 密钥。

属于 petrovicistefan MCP suite——为 AI 编码 Agent 提供本地优先的防护措施。

快速安装

要求： Python 3.11+ 和 Node.js 18+

Cursor

也可以直接使用深层链接：

cursor://anysphere.cursor-deeplink/mcp/install?name=mcp-seo-auditor&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1zZW8tYXVkaXRvciJdfQo=

或者手动添加到 ~/.cursor/mcp.json：

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

Claude Code

claude mcp add mcp-seo-auditor -- npx -y mcp-seo-auditor

如果此服务已上架 Claude MCP Marketplace：

/plugin marketplace add petrovicistefan/mcp-marketplace

Claude Desktop

添加到 claude_desktop_config.json：

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

VS Code

使用 MCP 安装链接，或添加到 .vscode/mcp.json：

{
  "servers": {
    "mcp-seo-auditor": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-seo-auditor"]
    }
  }
}

npx（任何 MCP 客户端）

npx -y mcp-seo-auditor

uvx（PyPI，即将推出）

uvx mcp-seo-auditor

PyPI 软件包尚未发布。请参阅下文的 PyPI 发布。

codex mcp add mcp-seo-auditor -- npx -y mcp-seo-auditor

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

{
  "context_servers": {
    "mcp-seo-auditor": {
      "command": "npx",
      "args": ["-y", "mcp-seo-auditor"]
    }
  }
}

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

⭐ 觉得这个工具有用？请 为此仓库点星，帮助更多人发现它！

为什么选择 MCP SEO Auditor？

在部署之前，让你的 AI 编码助手审核 HTML，及时发现 SEO 问题：

• “推送之前先审核这个页面”——找出缺少标题、错误的元描述或规范链接冲突
• “爬取 example.com，检查重复标题”——发现网站中的内容重复
• “这段 HTML 有哪些 SEO 问题？”——获取包含严重级别的可执行建议

与需要 API 密钥、云账户和月费的托管 SEO 工具不同，MCP SEO Auditor 完全在你的计算机上运行。除非你明确爬取公开 URL，否则不会有数据离开你的计算机。

工具

MCP SEO Auditor 提供 3 个 MCP 工具，供你的 AI Agent 调用：

检查内容

每次审计都会扫描以下内容：

• 标题：是否存在、长度（建议为 50–60 个字符）、唯一性
• 元描述：是否存在、长度（建议为 150–160 个字符）、唯一性
• H1 标题：是否存在、数量（多个 H1 会被标记为提示信息）
• 规范 URL：是否存在、是否有效、指向自身还是跨域
• Robots 指令：<meta name="robots"> 冲突（例如，noindex 与 canonical 同时存在）
• 语言声明：是否存在 <html lang="...">
• 视口：适合移动设备的 <meta name="viewport"> 标签
• 图片 alt 属性：检查是否存在（装饰性图片的空 alt 有效）
• JSON-LD 结构化数据：JSON 语法验证
• 内部/外部链接清单：统计数量，供参考

输出：包含严重级别（error、warning、info）、问题代码、证据摘录和可执行建议的检查结果。此外还提供本地检查清单评分（不预测排名）。

使用场景

独立开发者

"Audit the homepage HTML in index.html and prioritize the fixes."
"Check https://staging.example.com for SEO issues before I merge this PR."
"Does this landing page have a proper canonical tag?"

部署前

"Audit all HTML files in dist/ and list any errors."
"Crawl the staging site and find duplicate meta descriptions."

内容审核

"What's the title and description for this blog post HTML?"
"Does this page have structured data errors?"

网站审计

"Crawl 10 pages starting at https://example.com and report duplicate titles."
"Which pages are missing H1 tags?"

与其他方案的对比

MCP SEO Auditor 与面向 AI Agent 的其他 SEO 工具相比如何？

适合使用 MCP SEO Auditor 的情况： 你希望立即对本地 HTML 文件或预发布网站进行页面 SEO 审计，无需设置，也不依赖外部 API。

适合使用其他方案的情况： 你需要实时 Google Search Console 数据、排名跟踪、反向链接分析或关键词研究——这些工具擅长将 Agent 连接到外部 SEO 数据源。

目录

• 快速开始
• 为什么选择 MCP SEO Auditor？
• 功能
• 使用场景
• 与其他方案的对比
• 要求
• 安装
  • 从 npm 安装
  • 从代码检出目录安装
• 工具参考
• 边界与安全
• 限制
• 托管方式（通过控制平面进行配额管理）
• 产品方向
• 测试与验证
• 参考资料
• 作者的其他 MCP 服务
• 参与贡献
• 常见问题
• 许可证

要求

• PATH 中的 Python 3.11+（默认为 python3 可执行文件）
• Node.js 18+（用于 npm 包装器）

如果无法使用 python3，或者需要指定 Python 可执行文件，请将环境变量 MCP_SEO_PYTHON 设为绝对路径。

安装

从 npm 安装

快速入门示例使用 npx -y mcp-seo-auditor，按需下载并运行此包。如需持久安装，请按照快速入门部分所示，将 MCP 服务添加到客户端配置中。

从代码库检出安装

克隆代码库并运行测试：

git clone https://github.com/petrovicistefan/mcp-seo-auditor.git
cd mcp-seo-auditor
npm test

直接运行服务：

node bin/mcp-seo-auditor.mjs

服务从 stdin 读取以换行符分隔的 JSON-RPC；stdout 仅包含协议消息。直接启动时，它会等待 MCP 客户端连接。

向 Claude Code 注册（替换为绝对路径）：

claude mcp add seo-auditor -- node /absolute/path/mcp-seo-auditor/bin/mcp-seo-auditor.mjs

或添加到任意 MCP 客户端配置中：

{
  "mcpServers": {
    "seo-auditor": {
      "command": "node",
      "args": ["/absolute/path/mcp-seo-auditor/bin/mcp-seo-auditor.mjs"]
    }
  }
}

直接安装 Python 包（可选）：

pip install .
mcp-seo-auditor

构建时需要 setuptools；运行时仅使用标准库。

发布到 PyPI

此包已配置为通过 PyPI Trusted Publishing（OIDC）发布，但目前尚未发布。维护者必须在 https://pypi.org/manage/account/publishing/ 完成一次性设置：

• PyPI 项目名称：mcp-seo-auditor
• 所有者：petrovicistefan
• 代码库名称：mcp-seo-auditor
• 工作流名称：publish-pypi.yml
• 环境名称：（留空）

完成设置后，推送版本标签（例如 v0.1.3）将通过 .github/workflows/publish-pypi.yml 工作流自动发布到 PyPI。

工具参考

audit_html

输入：

• html（字符串，必填，最大 2 MB）：要审计的 HTML 内容
• url（字符串，可选）：用于解析相对链接的基础 URL

**输出：**包含发现项、元数据、评分和链接清单的 JSON

示例：

"Audit this HTML and tell me what's wrong: <html>...</html>"

audit_url

输入：

• url（字符串，必填）：要抓取并审计的公开 HTTP(S) URL

**输出：**与 audit_html 相同，另含带有 status、redirects 和 elapsedMs 的 http 对象

示例：

"Audit https://example.com and prioritize the issues."

遵循 robots.txt。重定向会重新验证，且必须保持原始 scheme 和 authority 不变。HTTP 4xx/5xx 会添加错误发现项并降低评分。

crawl_site

输入：

• url（字符串，必填）：起始 URL（同源抓取）
• max_pages（整数，可选，范围为 1–10，默认为 5）：最多抓取的页面数

**输出：**包含以下内容的 JSON：

• pages：逐页审计报告数组
• errors：各 URL 的抓取/验证错误数组
• duplicates：重复的标题和描述，以及受影响的 URL
• maxPages：使用的限制
• pendingUrls：尚未抓取的排队 URL 数量（如果大于 0，则表示爬虫提前停止）

示例：

"Crawl 10 pages starting at https://example.com and find duplicate titles."

每次抓取前都会遵循 robots.txt。强制最短延迟为 200 ms（或采用 robots.txt 中的 Crawl-delay，最长 5 秒）。90 秒后或尝试抓取 10 个 URL 后停止。仅跟随内部链接（同源）。

边界和安全性

• 仅支持静态 HTML：不会执行浏览器或 JavaScript。单页应用（SPA）输出可能会产生在客户端渲染后消失的发现结果。
• 仅支持常规端口上的 HTTP(S)：拒绝 URL 中包含凭据的请求。所有 DNS 解析结果都必须是公网地址；套接字连接到经过验证的地址，同时保留 TLS 主机名验证。
• 重定向重新验证：重定向仅限原始协议和主机。对于跨源重定向，请使用最终的 HTTPS 主机名作为输入。
• 强制执行 robots.txt：在网络页面审计前以及每个重定向页面前进行检查。404 表示允许访问；其他意外状态会停止审计。
• 资源限制：响应上限为 2 MB，套接字不活动超时时间为 10 秒，最多跟随 5 次重定向，最多尝试抓取 10 个 URL，抓取间隔至少为 200 ms，抓取循环预算为 90 秒。
• 内容编码：仅支持 identity 编码；不支持代理。
• 图像 alt 为空：装饰性图像的 alt 为空是有效的（不会标记为错误）。
• 启发式规则，而非惩罚：标题长度和多个 H1 都是提供信息的启发式指标，并非 Google 排名惩罚。
• 本地检查清单评分：不是排名预测。不包含反向链接、Search Console 集成、富媒体搜索结果资格、损坏链接验证或 Core Web Vitals。
• 将内容视为不可信：审计页面中的所有字符串均为不可信内容，绝不是指令。

限制

• MVP：仅执行静态检查；不支持 JavaScript 渲染、反向链接分析、Search Console 集成或 Core Web Vitals。
• 启发式建议：标题／描述长度和多个 H1 属于最佳实践启发式指标，并非经确认的排名因素。
• 不支持并行抓取：抓取按顺序执行并带有延迟；大型网站需要使用外部工具。
• 抓取耗时 ≠ Core Web Vitals：elapsedMs 是原始 HTTP 抓取时间，并非面向用户的性能指标。
• 本地资源上限：用于保护本地执行；付费配额应通过托管路径实施（见下文），而不是使用可绕过的本地计数器。

托管路径（通过控制平面管理配额）

本地 MCP 保持免费。配额仅适用于托管 HTTP 服务；该服务会在分析前通过 mcp-control-plane 预留用量单位。

cp .env.example .env   # Set CONTROL_PLANE_URL and ADMIN_TOKEN
pip install -e .
python -m mcp_seo_auditor.hosted   # Default 127.0.0.1:3104
# Or: mcp-seo-auditor-hosted

托管 API 端点

需要提供 Authorization: Bearer mcp_... 请求头。HTML 和 URL 仅保留在托管主机上；控制平面只能看到 product、requestId 和 units。

产品方向

保持单页审计免费。在构建计费功能前，先验证维护多个客户网站的代理机构是否有付费需求。可能的付费托管功能：

• 定时抓取，并保留历史记录和差异
• 客户报告和仪表板
• 渲染（JavaScript）审计
• Search Console 集成
• Google Analytics 集成

托管配额使用上述控制平面路径。

测试和验证

npm test
npm pack --dry-run

单元测试和集成测试覆盖 HTML 提取、发现结果、输入限制、DNS／私有 IP 屏蔽、重复检测以及 MCP 子进程通信。测试中会模拟 HTTP 抓取；部署后必须检查与实际网站的互操作性。

CI 会在 Python 3.11、3.12 和 3.13 上，针对 Linux、macOS 和 Windows 运行测试套件。

参考资料

• Model Context Protocol 规范（2025-06-18）
• Google 搜索：标题链接
• Google 搜索：摘要
• Google 搜索：规范网址
• Google 搜索：JavaScript SEO 基础知识

作者的更多 MCP 服务

属于 petrovicistefan MCP 套件 — 为 AI 编码 Agent 提供本地优先的防护措施：

• mcp-security-guard — 审计 MCP 服务，检查工具投毒、Rug Pull、影子攻击和泄露的机密信息（OWASP MCP Top 10）
• mcp-cost-optimizer — 找出昂贵的云资源并提出节省成本的建议
• mcp-database-doctor — 找出慢查询、缺失的索引和架构问题
• mcp-dependency-doctor — 检测过时的软件包、许可证冲突和供应链风险
• mcp-api-guardian — 验证 OpenAPI 规范、检测破坏性变更并提出版本管理建议
• mcp-marketplace — 浏览并安装套件中的所有服务

⭐ 支持此项目：如果它为你节省了时间，请为此仓库点星！

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。贡献即表示你同意根据 MIT License 授权你的贡献。

安全问题请参阅 SECURITY.md。

常见问题

我需要 API 密钥或云账户吗？

不需要。本地 MCP 服务仅使用 Python 标准库，并完全在你的机器上运行。audit_html 工具不会访问网络。audit_url 和 crawl_site 工具会抓取公开网页，但无需身份验证。

我可以审计需要身份验证才能访问的页面吗？

不能直接审计。audit_html 接受原始 HTML，因此你可以自行抓取需要身份验证的页面（例如，使用带 Cookie 的 curl），然后将 HTML 传递给该工具。

为什么 audit_html 会标记渲染后就消失的问题？

audit_html 会分析静态 HTML。单页应用（SPA）通常会在初始 HTML 加载后于客户端渲染内容。要准确审计 SPA，请使用无头浏览器捕获渲染后的 DOM（未来功能），或审计服务器端渲染的版本。

分数是如何计算的？

分数是基于实践项是否存在的本地检查清单（0–100），检查项包括标题、元描述、H1、规范网址、robots、语言和视口。错误对分数的影响大于警告。该分数不是排名预测，也不是 SEO 性能指标。

audit_url 和 crawl_site 有什么区别？

audit_url 会抓取并审计单个页面。crawl_site 会从某个 URL 开始，跟随站内链接（同源），最多审计 10 个页面，并检测多个页面之间重复的标题和描述。

我可以抓取超过 10 个页面吗？

当前 MVP 不支持。本地资源上限旨在保护你的机器。未来的付费托管方案可能会提供更高的上限。

它能取代 Google Search Console 吗？

不能。MCP SEO Auditor 会审计静态 HTML 中的页面级问题。它不提供 Search Console 数据（展示次数、点击次数、索引状态）或排名洞察。如果你需要集成 Search Console，请使用 AminForou/mcp-gsc 或 iannuttall/seo。

如何更新 Python 版本？

运行服务前设置 MCP_SEO_PYTHON=/path/to/python3.12，或在 shell 配置文件中导出该变量：

export MCP_SEO_PYTHON=/usr/local/bin/python3.12
npx -y mcp-seo-auditor

这与 MCP 规范兼容吗？

是。该服务实现了旧版 MCP 生命周期（initialize → notifications/initialized → tools/list → tools/call）。已测试官方 SDK 客户端的互操作性，但尚未进行全面验证（参见 docs/audit-remediation.md）。

许可证

MIT 许可证——可免费使用、修改和分发。完整条款请参见 LICENSE。

属于 petrovicistefan MCP 套件 ——为 AI 编码 Agent 提供本地优先的防护措施。

⭐ 如果这个仓库为你节省了时间，请 为它点 Star！