iannuttall/seo: an SEO audit CLI and MCP server for AI agents

The gap iannuttall/seo fills for agents that need SEO evidence

Most SEO tooling assumes a human at a dashboard. An agent asked to fix a site has no equivalent: it either guesses from page HTML or gets handed a screenshot. The README states the project exists to give agents "real crawl, Search Console, traffic analytics, keyword, result, domain, competitor, and link evidence through MCP and one packaged SEO skill instead of screenshots or guesses." That is the specific problem. The output is not a score; it is a set of findings with the crawl row or provider row behind each one. The stated audience is three groups: people auditing their own sites who do not want a heavy dashboard, AI agents consuming evidence over MCP, and developers embedding the report engine in a script, a CI job, or a TypeScript app. The package is published on npm as `seo` under Apache-2.0, and the repository is a pnpm and Turbo monorepo with `apps/`, `packages/`, `skills/` and `evals/` directories at the top level.

How the report engine separates evidence from findings

The design rule the README is most explicit about is layering. Observed evidence stays separate from derived findings and recommended actions, so a claim can be traced back to the crawl row or provider row that produced it. Three further rules follow from that. Partial data is never reported as a zero: a capped, filtered or sampled source is labelled, and it cannot support a definitive all-clear. Heuristics are labelled as heuristics, so a convention or threshold is not presented as a search-engine rule. And every recommendation carries a way to check whether the fix worked rather than a promise about rankings or traffic. That last point is the honest part of the design and also the limiting one. If you want a tool that tells you a change will raise traffic, this is not it. The default report uses whatever evidence you have connected, states what it could not check, and ends with a short list of follow-up commands. Crawls can be saved and compared, so a second run does not repeat the first. The package also exposes a provider SDK entry point, which is how the optional third-party research providers plug in.

Installing iannuttall/seo and running a first audit

The README requires Node 22 or newer; package.json is stricter and sets `engines.node` to `>=22.19.0`. Install globally from npm, then run the setup walkthrough and the main report.

npm i -g seo
seo start
seo report

`seo start` walks through Google sign-in, your Search Console property, an optional traffic analytics connection, and a local project profile. Public releases can include a shared Google app; if it is unavailable in your build, the setup guides you through adding your own desktop OAuth client. If you would rather not connect Google at all, the README gives a local-only path that crawls a URL and returns findings plus an action list with no sign-in.

seo report --url https://example.com

When a profile already exists, the same command can run against a Search Console property directly instead of a URL.

seo report --site sc-domain:example.com

For agents and scripts, the report is available as structured JSON, and the MCP server installs into local MCP clients.

seo report --json
seo mcp install

The README notes that after install the `seo` command is available in every terminal, script, CI job and local MCP client on the machine. `seo help` prints the command list, and `seo help all` prints a longer one.

The commands that turn a report into a work queue

A report that lists every warning equally is not actionable, so the tool ranks. `seo refresh-priorities` ranks the next best SEO actions, and the README says ranking uses affected URLs, rule severity, search visibility and analytics value rather than treating each warning the same. Several commands target a specific kind of opportunity. `seo quick-wins` looks for ranking positions 4 to 10 with low click-through rate. `seo second-page` investigates URLs averaging positions 10 to 20. `seo technical-watch` crawls and monitors index status over time. On the research side, keyword ideas, market estimates and current results come from optional DataForSEO, Semrush or Ahrefs connections built into the main package, and the README is explicit that you should connect one only when external result, keyword, domain, competitor or link evidence would change the decision. Useful terms can be kept in local saved sets. Competitor work looks for recurring search competitors, inspects their ranking pages, and filters possible keyword gaps through Search Console data and existing provider rankings. `seo export diagnose` writes report data to CSV, and `seo reports list` discovers every structured report. The command names and their descriptions are all from the README's `seo help` output.

Where iannuttall/seo is the wrong tool

The first constraint is platform. This is a Node command line tool and an MCP server, not a hosted product. There is no web dashboard described in the README, and the report lives in your terminal, your JSON output or your CSV export. If your team needs shared dashboards and scheduled email digests, you are looking at the wrong category of software. The second constraint is the data source. Search Console and connected traffic analytics are Google properties, and the setup runs a Google sign-in. A site whose search data lives elsewhere gets the crawl-based technical report and little of the demand analysis. The third is the optional research providers. Keyword, competitor and link evidence depends on a paid DataForSEO, Semrush or Ahrefs connection, and the README frames that as a conditional purchase rather than a default. The fourth is the honesty rule itself: the tool will not give you a definitive all-clear when a source was capped, filtered or sampled, and it will not promise ranking or traffic outcomes. Teams that want a confident single number will find that frustrating. Finally, the README's own setup text notes that a build may ship without the shared Google app, in which case you supply your own desktop OAuth client before first-party data works at all.

How it compares with Screaming Frog and hosted SEO suites

The closest single-purpose comparison is a desktop crawler such as Screaming Frog. Both crawl a site and report technical findings across metadata, links, indexability, canonicals, structured data, performance, security, mobile, international SEO and social previews, which is the checklist the README lists. The difference is what happens after the crawl. A desktop crawler presents a table for a human to read. iannuttall/seo is built to be consumed by a program: deterministic JSON, Markdown, stable rule IDs and a compact local MCP surface, with saved crawls that can be compared across runs. The second difference is the demand side. A crawler sees the site; this tool joins the crawl to Search Console and analytics so that priority ranking can weigh search visibility and analytics value, not just rule severity. Hosted SEO suites cover similar ground but keep the data on their servers. Here the README's stated position is local-first: your crawl, your property data, your project profile on your machine. That is the trade. You give up a shared interface and vendor-run scheduling, and you get a command that scripts and agents can call directly. The Apache-2.0 licence and the published provider SDK entry point also mean the report engine can be embedded rather than only invoked.

Maintenance, licence and what an upgrade costs

The repository is not archived, and the last push was on 2026-09-06. The published package version in package.json is 0.2.40, which is pre-1.0, so command output and JSON shapes should be treated as movable. The README promises stable rule IDs, which helps scripts that key off them, but a minor version bump can still change report contents. The monorepo pins its package manager to [email protected] and builds with Turbo and tsdown, so contributors need that toolchain; end users installing from npm do not. Licence is Apache-2.0, which permits commercial use and modification and requires that you keep the licence and notice files. The package ships PRIVACY.md, SECURITY.md, TERMS.md and TRADEMARKS.md alongside the code, so read those before redistributing under your own name. Nothing here is legal advice. On upgrade cost, the practical exposure is the OAuth setup: if you supplied your own desktop OAuth client because the shared app was unavailable in your build, that configuration is yours to maintain across versions. There is no release history documented, so there is no migration guide to point at.

Editorial conclusion

Adopt it if you already run an MCP-capable agent or want SEO checks inside a CI job, and you are comfortable with Node 22 or newer and a local project profile. Skip it if you want a hosted dashboard, a non-Google analytics source, or a tool that works without a Google sign-in for anything beyond a single-site crawl. Verify first that `seo report --url` returns useful findings on your own site without any sign-in, then check whether your Google Cloud project can supply a desktop OAuth client if the shared app is unavailable in your build.

Frequently asked questions

Official sources

1. iannuttall/seo on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README