Seo

SEO Skill

The only SEO skill your agent needs. 50+ SEO audit tools through a local CLI and MCP server, using your own crawl, Search Console, and Google Analytics data.

Get started · Documentation · npm · Questions · Privacy · Security · License · Agent notes

The seo command runs a full SEO audit from your terminal, turning a local crawl and your own search data into work you can inspect and ship. Find technical blockers, recover search demand, improve pages already close to more clicks, and catch regressions after a release.

Who this is for

• People running their own sites who want a clear audit and a ranked list of

fixes, without learning a heavy dashboard.

• AI agents that need real crawl, Search Console, and Google Analytics evidence through MCP

and one packaged SEO skill instead of screenshots or guesses.

• Developers who want to embed the same report engine in a script, a CI job, or

a TypeScript app.

Quick start

Requires Node 22 or newer.

npm i -g seo
seo start
seo report

The setup walks you through Google sign-in, your Search Console property, an optional Google Analytics property, and a local project profile. Public releases can include the shared Google app. If it is unavailable in your build, setup guides you through adding your own desktop OAuth client.

That is the normal path. The seo command is then available in every terminal, script, CI job, and local MCP client on the machine.

The main report uses the evidence you have, explains what it could not check, and recommends a short list of follow-up commands. You can start with a local technical report before connecting Google.

Running seo help shows the shape of the tool:

seo v0.2.14

Run SEO audits, find what needs fixing, and ship the changes with your agent.

Start here
  seo start                                Connect Google and save a project profile
  seo report                               Run the main SEO report for the default project
  seo report --site sc-domain:example.com  Run without a profile
  seo report --url https://example.com     Start with a local technical report

Projects
  seo projects list  List saved project profiles
  seo projects add   Create or update a project profile
  seo sites          List Search Console properties
  seo doctor         Check local auth and config

Act on a report
  seo refresh-priorities  Rank the next best SEO actions
  seo quick-wins          Find ranking 4-10 low-CTR wins
  seo second-page         Investigate URLs averaging positions 10-20
  seo technical-watch     Crawl and index-monitor a site

Agent and power tools
  seo report --json    Run the main report as structured JSON
  seo export diagnose  Export report data to CSV
  seo mcp install      Install SEO tools into MCP clients
  seo skill list       Show the packaged SEO skill
  seo reports list     Discover every structured report

Use `seo help ` or `seo  --help` for command help.
Use `seo help all` for the longer command list.

What you get

• Find technical blockers across metadata, links, indexability, canonicals,

structured data, performance, security, mobile, international SEO, and social previews.

• Rank the work using affected URLs, rule severity, search visibility, and

analytics value instead of treating every warning equally.

• See why a finding matters, what evidence supports it, how to fix it, and how

to verify the change.

• Save and compare crawl reports without running the same crawl again.
• Measure SEO changes with matched before and after Search Console windows.
• Give scripts and agents deterministic JSON, Markdown, stable rule IDs, and a

compact local MCP surface.

How the reports stay honest

The point of a report is to be defensible, so the design keeps a few rules:

• Observed evidence stays separate from derived findings and recommended

actions. You can always see the crawl row or provider row behind a claim.

• Partial data is never reported as a zero. A capped, filtered, or sampled

source says so, and it cannot support a definitive all-clear.

• Heuristics are labeled as heuristics. A convention or threshold is not

presented as a search-engine rule.

• Each recommendation comes with a way to check that the fix worked, rather than

a promise about rankings or traffic.

Everyday use

seo start can save a project profile, which is a local shortcut for a site, Search Console property, Google Analytics property, and brand terms. If you have one default project, most commands need no flags.

seo report
seo refresh-priorities
seo quick-wins
seo second-page
seo technical-watch

Use --project when you have more than one:

seo report --project example
seo projects list

You can also work without a saved profile:

seo report --site sc-domain:example.com
seo report --url https://example.com
seo crawl https://example.com
seo audit-page --url https://example.com/pricing

seo report --url crawls the site and saves technical evidence. It does not pretend to know traffic, queries, or rankings until you add a Search Console property with seo start.

Run seo help for the short path or seo help all for the full command list.

Google Analytics commands sit under their provider namespace. List the properties available to the connected account, then run a report with the property you need:

seo analytics google properties
seo analytics google report --property 123456789 --dimensions landingPage --metrics sessions,totalUsers

Bing Webmaster is optional. Connect it when you want Bing traffic trends, crawl changes, and query and page opportunities beside your Google evidence:

seo providers bing connect
seo providers bing report --project example

The guided connection asks for the API key from Bing Webmaster Tools Settings, then API Access. It validates the key, lists verified sites, matches one to the selected project when the hostname is unambiguous, and stores the key in the system keychain with a private local file fallback. Agents and CI can set SEO_BING_API_KEY and run the report without saving the key.

The report compares recent traffic periods, highlights material crawl changes, and returns bounded query and page review lists. Provider responses stay uncached and byte limited. Invalid, partial, capped, unavailable, and sampled evidence remain distinct. Bing's inIndex crawl statistic is provider evidence, not URL-level proof that a page is indexed. A query or page missing from a weekly top list is unknown, not zero.

Use the same connection to review a bounded set of referring links, or import an export from another source:

seo links --project example --json
seo links --file ./links.csv --row-limit 10000 --json

CSV and JSONL imports stream from disk. Regular JSON arrays have a smaller file limit to avoid a memory spike. Every result includes the number of rows read, rejected, deduplicated, omitted, or stopped by a limit. It is evidence from the selected source, not a complete backlink index or an authority score.

Create an HTML report for a client

The built-in renderer creates a standalone report when you need a predictable file without asking an agent to design it:

seo report --project example --format html
seo monthly-report --project example --format html
seo report-narrative --project example --format html --view analyst

Client view keeps the presentation concise. Analyst view adds evidence coverage and unavailable sections. Use --output ./report.html to choose the file path. The file contains its own CSS, works offline, prints cleanly, and is marked noindex,nofollow.

An agent can instead design its own report from the structured result:

seo report --project example --full --json > seo-report.json

Ask the agent to turn that evidence into one responsive, print-friendly HTML file for the intended audience. It can choose the layout and visual style, but it must keep provider labels, reporting dates, data status, limitations, and verification steps visible. Missing or partial data must not become zero, and the presentation must not invent forecasts, causes, scores, or conclusions. The installed skill teaches agents this contract automatically.

Analyze crawler traffic in server logs

Stream a local NGINX or Apache-style combined access log without importing or retaining every raw request:

seo server-logs analyze --file ./access.log --json
seo server-logs analyze --file ./access.jsonl --format jsonl --json

The report groups observed search and AI crawler user agents by response class and path. Input bytes, rows, line size, unique paths, and returned detail are bounded, and any capped or malformed evidence stays visible. User-agent names can be spoofed, so the result describes observed request strings rather than verified crawler identity.

Notify IndexNow after a change

Generate a key file in the public asset directory for your site, then deploy it before sending notifications:

seo indexnow setup --site https://example.com --output ./public
seo indexnow verify --site https://example.com
seo indexnow submit --site https://example.com --url https://example.com/changed-page

Use --dry-run --json to validate a submission without notifying IndexNow. The command accepts one URL, a comma-separated list, or a newline-delimited file. A run is limited to 1,000 unique URLs, every URL must use the configured host, and the public key file is checked before a live request. The local key mapping stays in the system keychain with a private file fallback. Agents and CI can set SEO_INDEXNOW_KEY for the current process instead.

An accepted IndexNow request confirms receipt only. It does not prove that a URL was crawled, indexed, ranked, or shown in search results.

Crawl a site

For a large or unfamiliar site, start with the sitemap health pass:

seo crawl --sitemap-url https://example.com/sitemap.xml --health --format pretty

This reads the sitemap, then checks each listed URL for status, redirects, robots decisions, network failures, and access blocks. It does not parse or render page bodies, join Google data, check external links, or write page and robots responses to the local cache. Requests begin one at a time and increase only after clean responses.

Run the full crawl second when the health evidence points to a problem, or when you need metadata, canonicals, indexability, links, structured data, or page content:

seo crawl https://example.com --format pretty

Save it, export it, or compare it with an earlier crawl:

seo crawl https://example.com --save
seo crawl https://example.com --format html --output report.html
seo crawl-reports
seo crawl-reports --compare latest --against previous

Useful crawl controls include --max-pages, --max-depth, --include, --exclude, --no-sitemap, --no-external, and --fail-on for CI. Every request uses the stable versioned identity SEO-Skill/ (+https://seoskill.dev).

If a site denies or challenges that identity, the report keeps the HTTP status, provider indicators, request ID when available, and practical access guidance. Do not allow requests based on User-Agent alone because it can be spoofed. Scope any temporary exception to the audit machine source IP, required host or paths, and the exact blocking rule.

Use it in CI and scripts

JSON mode never prompts. Pass the site or project explicitly in unattended runs.

seo report --project example --json
seo crawl --sitemap-url https://example.com/sitemap.xml --health --format junit --output sitemap-health.xml --fail-on high
seo crawl https://example.com --json --output crawl.json

Reports keep observed data, derived findings, skipped sections, limits, and provider errors separate so automation can make decisions without parsing terminal prose.

seo report --json returns a compact summary, action queue, and bounded crawl evidence so an agent can choose its next call without loading every raw report. Use --full only when a script needs the complete report object.

When a CI job needs Search Console or Google Analytics data, give it a Google service account JSON key through its secret store. The service account needs access to the exact properties it will query. This GitHub Actions step runs without a browser or a copied local token:

- name: Run the SEO report
  run: |
    npm i -g seo
    seo report --site sc-domain:example.com --json > seo-report.json
  env:
    SEO_GOOGLE_SERVICE_ACCOUNT_JSON: ${{ secrets.SEO_GOOGLE_SERVICE_ACCOUNT_JSON }}

The Google data guide covers Search Console and Google Analytics permissions, mounted secret files, and how to check the active identity safely.

Agents can discover and run the same report catalog as MCP without starting a server:

seo reports list --category crawl --json
seo reports describe audit-page --json
seo reports run audit-page --params '{"url":"https://example.com"}' --json

Always describe a report before constructing its parameters. The CLI and MCP surfaces read from the same registry, so their ids and JSON Schemas cannot drift.

Use it with AI agents

Your agent carries one short SEO skill, and the CLI and MCP server do the heavy lifting. The skill teaches an agent how to discover the 50+ audit and report tools at runtime, and the agent asks the CLI for the detail on each tool only when it is about to run it. You get the whole toolkit without fifty skill files sitting in the context window on every session.

seo start offers to install the SEO skill during setup. If you skipped that step or need to reinstall it later, run the packaged installer:

seo skill install

If you also skipped the MCP step, install the local server into a supported client:

seo mcp install

The prompt detects installed clients. Scripts can choose one or more explicitly:

seo mcp install --codex
seo mcp install --claude-code
seo mcp install --cursor
seo mcp install --claude-desktop

Your client starts the server when it needs it. Run it directly only for manual configuration or testing:

seo mcp serve

The repository ships one skill under skills/seo. It is a router: it teaches an agent to discover reports, describe one to load its depth at runtime, inspect the evidence, and request a smaller follow-up instead of loading a giant result into context. Per-report guidance lives in the registry and is fetched with seo reports describe --json, so it never drifts from the skill.

The npm package includes the same file for local inspection:

seo skill list
seo skill path seo

Agents can also discover the canonical skill from https://seoskill.dev/.well-known/agent-skills/index.json. The entry links to the canonical skill instructions and includes a content digest for verification.

See MCP and agents for setup and tool details.

Use it as a library

Install the same unscoped package in any Node 22 or newer project:

npm install seo

Run any public report by id with the same definition, input schema, and evidence used by the CLI and MCP server:

import { describeReport, executeReport } from 'seo/mcp'

const description = describeReport('quick-wins')
const result = await executeReport('quick-wins', {
  site: 'sc-domain:example.com',
  days: 90,
})

console.log(description.inputSchema)
console.log(result)

Or call typed analysis functions directly when your app already knows the job it needs to run:

import { auditPage, crawlSite } from 'seo'

const page = await auditPage({
  url: 'https://example.com/pricing',
})

const health = await crawlSite({
  url: 'https://example.com',
  mode: 'sitemap',
  strategy: 'health',
  sitemapUrl: 'https://example.com/sitemap.xml',
})

const crawl = await crawlSite({
  url: 'https://

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [iannuttall](https://github.com/iannuttall)
- **Source:** [iannuttall/seo](https://github.com/iannuttall/seo)
- **License:** Apache-2.0
- **Homepage:** https://seoskill.dev

Install and usage instructions live in the source repository linked above.