iannuttall/seo · 上手攻略

  • 仓库：iannuttall/seo
  • 链接：https://github.com/iannuttall/seo
  • 分类：agent
  • 作者：Tom
  • 更新：2026-10-22

§0 三证 checklist 与自检

项目 状态 证据
GitHub URL（已 fetch） ✅ 已抓取 README（raw main）、package.json、CHANGELOG.md、repo API
版本锚点 ✅ npm seo@0.11.0（registry.npmjs.org/seo/latest 返回 tarball seo-0.11.0.tgz）；repo package.json version 0.11.0；mcpName: dev.seoskill/seo；许可证 Apache-2.0
README 子模块 anchor ✅ CHANGELOG.md、CONTRIBUTING.md、PRIVACY.md、SECURITY.md、TERMS.md、TRADEMARKS.md、外部 iannuttall/seo-provider-template；文档站 seoskill.dev/docs
顶会 / 论文 venue ⚠️ 无论文、无学术 venue；是工具型产品仓库
作者归属 ✅ package.json author: "Ian Nuttall"；仓库 owner iannuttall（Ian Nuttall，SEO 领域知名从业者），docs 站 seoskill.dev

诚实声明：本篇所有命令与行为均来自 README / CHANGELOG 原文，未实机运行（按任务边界不 clone、不跑代码）。涉及"免费额度""托管服务器保存什么"的表述以 README 与隐私政策描述为准，付费 DataForSEO/Ahrefs 成本数字取自 CHANGELOG 明写的估值。

§1 这是什么

iannuttall/seo 是一个 Google Search Console 的 MCP Server + CLI，作者自述定位是 "SEO for agent-native teams"。它不是给 agent 塞一份 SEO 检查清单，也不是塞第三方估算的关键词量，而是把你自己的真实数据接进来：

  • Search Console：点击、展示、平均位置
  • Google Analytics 或 Clicky：落地页与会话
  • Bing Webmaster Tools：Bing 侧数据
  • Google 更新日期（算法更新事件）
  • 站点爬取（技术问题 + AI agent 可读性）

仓库对应 npm 包 seo（Apache-2.0），同时提供两种接入方式：托管 MCP server（https://seoskill.dev/mcp，走 HTTP remote MCP）和本地 CLI + 本地 MCP（npm i -g seo，登录与数据留在本机系统 keychain）。

§2 解决什么问题

作者的诊断有三条，都很具体：

  1. Agent 的 SEO 建议是"通用清单" —— 问"为什么流量掉了"，agent 会给你一份整齐的可能原因列表（算法更新 / 技术问题 / 内容质量），但没有一条来自你的站点，所以没法执行。修法是把数字给它。
  2. Ahrefs / Semrush 的流量是估算 —— 它们从样本推算，漏掉大部分长尾，彼此数据还对不上。修法是从 Search Console（Google 的真相来源）起步；确实需要关键词量或竞品数据时，用你自己的 DataForSEO 或 Ahrefs key，并且把估算值和真实值分开存放。
  3. Agent 相信自己的编辑 —— 改完页面它以为生效了，实际还 noindexed、还跳转、还没进 Google。修法是查线上：seo page / seo index / seo crawl。

设计哲学上还有一条值得记：第一版有约 70 个命令，几乎没人用，于是砍到只剩少数几个；现在每个命令只接受站点或 URL（外加可选日期），没有设置项要调，每条结果结尾都给出下一条该跑的命令，让 agent 永远知道下一步去哪。

§3 快速安装

3.1 接 MCP（托管版，最快）

# Claude Code
claude mcp add --transport http seoskill https://seoskill.dev/mcp

# Codex
codex mcp add seoskill --url https://seoskill.dev/mcp

Cursor、Claude Desktop、VS Code 等：直接把 https://seoskill.dev/mcp 作为 remote MCP server 加进去。

3.2 CLI（爬取与 Bing 在本机跑）

npm i -g seo
seo start

seo start 会引导你登录、连接 agent 并安装 skill：选一个能看到你 Search Console 的 Google 账号完成 OAuth 授权（无密码、无注册表单）。CHANGELOG 0.8.2 起，seo start 会先问你希望的登录方式：登录/创建免费 seoskill.dev 账号（推荐，这样 CLI 与托管 MCP 共享 Google 账号、Bing 和 key）、仅在本机用 Google 登录、或跳过。

若 MCP 配置里走 npx，按 0.11.0 的更新提示，用 seo@latest 并重启客户端。

§4 核心用法

4.1 命令全表（README 明列）

命令 返回什么
seo report Search Console 总览，加各区块 top 行
seo page 单个 URL：线上页面、Google 索引状态及其 queries
seo compare 某日期前后的对比，并标出期间 Google 更新
seo index 点击下滑的页面，逐个线上+Google 校验
seo research 用你自己的 key 取关键词、SERP、竞品、外链
seo data 原始 Search Console 或 Bing 行数据
seo analytics Google Analytics 或 Clicky 的落地页
seo crawl 全站技术问题与 AI agent 可读性（仅 CLI）
seo internal-links 全站或单页的内链建议（仅 CLI）

每个命令同时也是同名 MCP 工具（下划线形式，如 seo_report），任何命令加 --json 输出 JSON，便于脚本化。

4.2 典型提问

"为什么 example.com 上个月的点击掉了？是核心更新吗？"
"哪些页面已经接近第一页，它们排什么词？"
"这个页面被索引了吗？没被索引为什么？"
"这个页面在哪些它从未提及的搜索词上出现过？"
"ChatGPT、Claude、Perplexity 能读到我的站点吗？"
"我在搜索里跟谁竞争？'vs' / alternatives 这类页面有需求吗？"

4.3 值得注意的新命令

  • seo research ai_answers --target <site>（0.9.0）：取站点自己 ai-queries 区块近 90 天里前 10 个"可问问题"，逐个到 ChatGPT search、Google AI Mode、Google AI Overview 问一遍，结果标为 cited / mentioned / neither / no answer / unavailable，并带日期、成本和 DataForSEO 报告的模型名。CHANGELOG 写明约 $0.12/次。
  • seo internal-links（0.10.0）：--site 全站审计或 --url 找指向某页的链接；爬取时优先走 sitemap，尊重 robots.txt 与其 crawl delay，跟随跳转与 canonical，靠文本与共同 Search Console query 找相关页，把链接放进真实句子 + 真实锚文本里，每个目标最多 8 条链接。全站审计默认爬 500 页，--max-pages 最高 5,000，结果里说明实际爬了多少页、是否触顶。0.10.0 的 JSON 结构有变更：methodology 被 crawl / judge / searchConsole / items / heldBack / pageInventory 取代。
  • 若配置了 TypeSafe key，0.10.0 的 internal-links 会启用名为 "Jev" 的分类器，给每个页面分类并判断链接意图、概率、句子、锚文本以及"对读者有什么用"；代码里写死的下限可以推翻它的判断。CHANGELOG 估算 500 页约 10–20 美分。没有 key 时它会说明"未使用 Jev"，退回文本启发式。

4.4 环境变量与开关

  • TYPESAFE_API_KEY：Jev 分类器的 key（也可存到 seoskill.dev 账号的 Keys 标签后 seo login）。
  • NO_UPDATE_NOTIFIER=1 或 --no-update-notifier：关闭更新提示；CI 中自动关闭（0.11.0）。
  • seo login：在已链接的机器上直接登录，跳过 seo start 的提问。

§5 典型适用场景

  1. "流量掉了"归因：有 Search Console 权限的运营/站长，把站点数据接进 Claude Code / Codex，直接问"上个月点击为什么掉"，得到基于真实行数据而非通用清单的答案。
  2. 内容团队的选题与内链：seo internal-links --site 找出互不连通但主题相关的页面，给出可执行的锚文本建议。
  3. AI 搜索可见度监测：seo research ai_answers 量化自己的站点在 ChatGPT / Google AI Mode / AI Overview 里是否被引用。
  4. 发版后索引体检：seo page / seo index / seo crawl 用来验证"页面到底进没进 Google"，防止 agent 自以为已优化完成。
  5. CI / 云端 agent：--json 输出可直接进流水线；官方文档有 "Cloud agents and CI" 专页。

§6 与同类对比

维度 iannuttall/seo Semrush / Ahrefs（AI 助手） 通用 MCP SEO server 纯 SEO 脚本组合
数据来源 你自己的 Search Console / GA / Clicky / Bing 厂商自有爬取 + 估算模型 多为估算或封装 SaaS 分散，需自己接 API
是否需要付费 key 免费起步；DataForSEO/Ahrefs/TypeSafe 额外付费 订阅制 视服务 视 API
交付形态 MCP server + CLI SaaS MCP 脚本
接入成本 一次 OAuth 授权 注册 + 订阅 装包 + 配 key 逐个写 glue code
独特能力 ai_answers 查 AI 答案引用、内链自动生成 关键词量/竞品库更强 视实现 无

核心差异：其它工具卖的是估算，这个工具卖的是你站点的真实第一方数据，并且刻意把估算层（DataForSEO/Ahrefs）与真实层（Search Console）在数据结构和文档里分开。

§7 坑与注意（工程节）

  1. 坑：以为只有 MCP 就够用。现象：接了 https://seoskill.dev/mcp 后让 agent 查全站技术问题和内链。影响：拿不到结果，因为 seo crawl 与 seo internal-links 是 CLI only（README 明确标注）。修复：再 npm i -g seo 并在本机跑这两个命令，让 agent 通过本地执行调用。
  2. 坑：Search Console 权限的 Google 账号选错。现象：OAuth 授权的账号看不到目标站点属性。影响：报告为空或 property 找不到。修复：授权时选能看到你 Search Console 的那个 Google 账号（README 原话），多 property 场景确认 site 参数填的是已验证属性。
  3. 坑：DataForSEO / Ahrefs 未配 key 时的预期错位。现象：seo research 的关键词量、竞品、外链拿不到或报错。影响：以为工具坏了。修复：这些依赖你自己的付费 key（seo login 存到 Keys 标签）；无 key 时该命令本身就不是完整能力，估算层与真实层本就分离。
  4. 坑：托管 server 与本地 CLI 的数据边界混淆。现象：以为所有数据都在本机。影响：隐私预期错位。修复：README 写明托管 server 保存你的已链接 Google 账号与任何你存下的 key（加密），不保存 Search Console 数据、报告与请求日志；CLI 的登录态存在系统 keychain。要完全本地化就走 CLI 路线。
  5. 坑：internal-links 的 JSON 结构变更导致脚本崩。现象：0.10.0 之前写好的解析代码拿不到 methodology 字段。影响：静默拿到 undefined。修复：按新结构 crawl / judge / searchConsole / items / heldBack / pageInventory 改写，并用 --json 做契约测试。
  6. 坑：爬取规模与费用失控。现象：--max-pages 拉满 5,000 页 + TypeSafe key 开启。影响：DataForSEO/TypeSafe 账单按量上涨（CHANGELOG 估算 500 页约 10–20 美分）。修复：先用默认 500 页跑通，看结果里"实际爬了多少页 / 是否触顶"再决定是否放大；不用 key 时它明确退回启发式、零额外成本。
  7. 坑：ai_answers 的付费调用。现象：每次跑都消耗 DataForSEO 额度。影响：意外账单。修复：CHANGELOG 估约 $0.12/次；0.9.0 起它会先用 DataForSEO 的免费国家/语言列表校验市场，不支持的市场不花钱；先小范围试。
  8. 坑：DataForSEO 的 "No Search Results" 被当报错。现象：0.9.0 之前这类返回走错误分支。影响：脚本把它当失败重试。修复：0.9.0 起它是空结果 + 成本，不是错误；部分结果会保留行并标 partial —— 解析时按"空/部分"而非"失败"处理。
  9. 坑：更新提示扰乱自动化输出。现象：新版本在终端 stderr / JSON 的 updateNotice / MCP 工具结果里追加一行。影响：严格解析输出或日志噪声。修复：CI 中自动关闭；需要手动关闭用 NO_UPDATE_NOTIFIER=1。
  10. 坑：本地缓存被占用导致报告失败。现象：并发跑多个命令时报 "database is locked"。影响：报告直接失败。修复：0.11.0 已修 —— 缓存忙时报告用临时缓存完成，不再失败；跨版本请确认 npm i -g seo 拿到的是 0.11.0 或更高。
  11. 坑（次要）：品牌与名称使用受限。现象：想在产品里直接用 "seo" 这套命名/图形。影响：违反品牌政策。修复：仓库 TRADEMARKS.md 单独约束名称与美术资源，Apache-2.0 只覆盖代码，不覆盖商标。
  12. 坑（次要）：命令数量认知错位。现象：以为有几十条命令可用。影响：按错误预期写提示词。修复：作者已刻意收敛为 9 条左右；文档以 seoskill.dev/docs 为准（README 提到第一版约 70 条命令被砍掉）。

§8 一句话推荐结论

推荐给做真实站点运营、且手里有 Search Console 权限的人：这是少见的把"第一方真实数据"而不是"关键词估算"喂给 agent 的实现，接入成本只有一次 OAuth 授权，免费起步，CLI + MCP 双通道还能按需本地化；但如果你的诉求是关键词量与竞品全库对比，它只是 Semrush 的补充而非替代，且 DataForSEO/Ahrefs/TypeSafe 三处付费点要提前算进预算。