SEOHEAD Tools

The local evidence and audit-automation layer for SEO specialists and tool-calling AI agents.

47 callable tools · 96 checks over Screaming Frog crawl exports · 28 workflow skills · CLI · local MCP · Docker

Website · Documentation

Quick start · Agent recipes · Inspect the real example · Scope and trade-offs

SEOHEAD is not a crawler replacement. Screaming Frog produces the CSV/XLSX exports consumed by SEOHEAD's 96-check analyzer. SEOHEAD then runs complementary bounded checks, keeps failed and unavailable measurements visible, and gives a specialist or tool-calling agent one tested CLI/MCP surface for assembling an audit, prioritized backlog, and reports.

The package brings live URL checks, infrastructure reconnaissance, structured-data work, log and content analysis, optional keyword/SERP/traffic sources, report generation, and agent playbooks into that workflow. Think of it as the automation and evidence layer around the crawler, not an alternative to the crawler or to specialist judgement.

The toolkit does not write strategy or client copy by itself. It collects evidence, applies deterministic checks, and returns structured data. A capable tool-calling agent can then combine those results into a site review, competitor brief, migration plan, prioritized backlog, or commercial-proposal draft while a specialist keeps control of interpretation.

Different jobs, one workflow

See how SEOHEAD fits with crawlers and data providers for the exact scope boundary.

Reproducible output from a committed synthetic fixture

The values above come from the committed synthetic fixture: 6 URLs, 18 issues, and 15 tasks. Open the generated audit.md and tasks.md, or reproduce them locally with seohead sf run --exports-dir examples/exports --out examples --tasks. No client data is included.

Related MCP server: mcp-seo

Choose your path

Why it is useful

A serious review repeatedly asks the same questions: what is indexable, what redirects, where canonicals point, whether hreflang is reciprocal, what Schema.org declares, which technologies and CDN are present, what bots can crawl, what the logs show, and how all of that becomes a deliverable. SEOHEAD turns this collection layer into reusable tool calls.

In the author's workflow, evidence collection and report scaffolding are often several times faster because one agent can run the same bounded checks, preserve their structured output, and assemble the first report pass. This is an experience statement, not a universal benchmark. Network conditions, crawl scope, provider quotas, and expert review still determine total time.

What is included

42 core CLI commands and MCP tools

Run seohead --help for the authoritative command list. Every core command goes through the same handler used by its seo_* MCP counterpart; a test gate fails if the interfaces drift.

Screaming Frog audit layer

Five additional sf_* MCP tools turn a Screaming Frog crawl into machine-readable evidence, compact summaries, filtered findings, an export inventory, and a prioritized task backlog.

The analyzer has a registry of 96 checks across metadata, indexability, canonicals, redirects, internal links, sitemaps, hreflang, structured data, page depth, HTML weight, performance signals, and other crawl-derived evidence. It applies the checks supported by the available exports; missing input is reported as skipped with a reason, never silently converted into “zero issues.”

Two modes are intentionally supported:

• Export mode analyzes existing CSV/XLSX exports and does not require SEOHEAD to run Screaming Frog.

• Live crawl mode launches the local Screaming Frog CLI and therefore requires an installed, active paid Screaming Frog SEO Spider licence. SEOHEAD does not bundle or replace that licence.

28 agent workflow skills

The repository ships 21 technical-audit playbooks in .claude/skills/ and seven broader SEO content/research playbooks in seohead/skills/. They teach an agent when to call tools, how to separate evidence from inference, and how to assemble outputs without pretending that an unmeasured signal is clean.

analytics-console-review describes a permissioned, read-only browser/export fallback when an official provider API is unavailable. The repository does not bundle a browser or provider login.

Quick start

Clone the repository and let one install command resolve the Python dependencies:

git clone https://github.com/PavloSEO/seohead-seotools.git
cd seohead-seotools
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[all]"

On Windows PowerShell, activate with .venv\Scripts\Activate.ps1.

Optional components stay optional:

• render adds Playwright-based raw/rendered comparison; install its Chromium separately;

• mcp adds the local stdio server;

• cluster adds scikit-learn clustering;

• reports adds DOCX/XLSX output;

• sitemap adds optional sitemap helpers;

• external providers require your own credentials and may charge their own fees.

One-command examples

# Bounded sitemap-based live evidence pass (not a link-graph crawl), then write an Excel file
seohead site-audit \
  --url https://example.com \
  --limit 25 \
  --report xlsx \
  --out report.xlsx

# Audit existing Screaming Frog exports without crawling again
seohead sf run \
  --exports-dir ./exports \
  --out ./report \
  --tasks

# Inspect one page and its infrastructure
seohead parse --url https://example.com
seohead headers-check --url https://example.com
seohead schema-check --url https://example.com
seohead domain-profile --domain example.com

# Build a connected Schema.org graph from facts visible on the page
seohead schema-build --url https://example.com/product/example

# Optimize images into a separate directory; source files stay untouched
seohead images-optimize \
  --files ./images \
  --output-dir ./optimized \
  --format webp \
  --quality 82

All commands also accept a JSON object through --input; without explicit flags, that object may come from stdin. See usage examples and the tool reference.

One audit document, five deliverables

report-build formats existing evidence without adding findings or making network requests. XLSX is a four-sheet working file; DOCX is a client deliverable; CSV, Markdown, and JSON preserve the same contract for import, review, and data exchange. See the report fixtures and field contract.

Local MCP server

Install the mcp extra, then register one stdio process in any compatible client:

{
  "mcpServers": {
    "seohead": {
      "command": "/absolute/path/to/.venv/bin/seohead",
      "args": ["mcp"]
    }
  }
}

The server exposes 42 seo_* tools plus five sf_* tools. The 42 core tools share the tested handler layer used by the CLI; the five SF tools expose the crawl workflow separately. The process opens no port, hosts no dashboard, stores no account, and sends no telemetry. File-producing tools return paths instead of dumping large reports into an agent context.

Docker and VPS use

The image is headless and exposes no network service:

docker build -t seohead-tools:local .
docker run --rm seohead-tools:local --version
docker run --rm seohead-tools:local parse --url https://example.com

For MCP, keep stdin attached and mount only the workspace the agent may read or write:

{
  "mcpServers": {
    "seohead": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/absolute/authorized/workspace:/data",
        "seohead-tools:local", "mcp"
      ]
    }
  }
}

On a VPS, the same container is launched by the local agent host. There is deliberately no public MCP endpoint in this repository. The image does not bundle Screaming Frog or a Playwright browser; export-mode SF analysis works, while live SF crawls and rendered checks use authorized host tools.

External data sources

Provider integrations are optional and explicit:

• Yandex Cloud supplies Wordstat expansion, seasonality, the region tree, and async Yandex SERP;

• Arsenkin supplies exact frequency where the Wordstat API does not;

• Yandex Metrika supplies counter configuration and traffic reports;

• DataForSEO supplies Google keyword and SERP data and defaults to its sandbox environment.

Secrets are read from environment variables or local configuration files and are never shipped. Paid calls are journalled before response parsing so a parser failure cannot make spend invisible. Read provider gotchas before enabling production credentials.

Safety and honest limits

• Network tools reject non-HTTP schemes and block private/non-public targets by default.

• File-changing operations require explicit intent; image optimization is non-destructive by default and validates output before reporting success.

• Security path probes, bot DNS verification, and sitemap live rechecks are opt-in.

• DataForSEO production mode is opt-in; its default is sandbox.

• Yandex SERP uses only the asynchronous endpoint.

• The toolkit does not discover the web-scale backlink profile of a domain.

• Lab browser timings are labelled as lab data, not field Core Web Vitals.

• backlinks-check verifies a donor list; it does not replace Ahrefs, Majestic, GSC, or another backlink index.

• International tools validate hreflang and regional structure; the package does not claim a machine-translation engine. Translation belongs to a reviewed model or localization workflow.

• site-audit is a bounded sitemap-based evidence pass, not an exhaustive run of all 42 core tools and not a replacement for a production crawler.

• SEOHEAD does not include its own general-purpose crawler. Whole-site crawling is delegated to Screaming Frog; export analysis remains available without live crawl mode.

Read SECURITY.md, architecture, and limitations before using outputs in a client deliverable.

Development

python -m pip install -e ".[dev,mcp,cluster,reports]"
ruff check .
ruff format --check .
pytest -q
seohead sf run --exports-dir examples/exports --out /tmp/seohead-report --tasks
python -m build

The suite contains 460 offline tests. CI also checks interface registration, layer boundaries, the synthetic crawl audit, package metadata, and English-only public documentation.

README visuals are generated from committed synthetic examples with scripts/render_readme_visuals.py; they are evidence views, not screenshots of a fictional dashboard.

Provenance and licence

The Python implementation and documentation are released under the MIT License. The bundled Schema.org vocabulary retains its original CC BY-SA 3.0 terms. Compatible upstream projects that informed individual algorithms are credited in THIRD_PARTY_NOTICES.md; no GPL or unlicensed source code is included. See PROVENANCE.md for the clean-snapshot policy and TRADEMARKS.md for the SEOHEAD name and terminal mark. Academic users can use the repository's citation metadata.