Local-first technical SEO audit automation

Turn SEO evidence into a reviewable technical audit

SEOHEAD is not a crawler replacement. It analyzes Screaming Frog CSV/XLSX exports, adds bounded live and infrastructure evidence, and produces traceable findings, prioritized tasks and reports through one CLI and local MCP.

View on GitHub

seohead — CLI

$ pip install -e ".[all]"
$ seohead parse --url https://example.com
$ seohead site-audit --url https://example.com --limit 25
$ seohead sf run --exports-dir ./exports --out ./report --tasks
$ seohead mcp   # local stdio server
# 47 tools · 96 crawl checks · 27 workflow skills

Verified product surface

One core, several evidence layers

Tools

42 shared seo_* tools plus five Screaming Frog sf_* tools

SF check registry

Applicable metadata, indexability, links, canonical, sitemap and hreflang checks

Workflow skills

Technical audit playbooks and broader SEO research/content methods

Report formats

XLSX, DOCX, CSV, Markdown and JSON from the same audit document

Who it is for

Less collection work, more specialist judgement

SEOHEAD Tools accelerates repeatable evidence collection and report scaffolding. It does not replace business context, implementation review or accountable SEO decisions.

Technical SEO specialists and consultants

Run repeatable checks and keep every conclusion linked to structured evidence.

One workflow for crawl analysis, bounded live evidence and a prioritized findings document.
Screaming Frog export analysis without manually rebuilding the crawl story.
Client deliverables in XLSX, DOCX, CSV, Markdown or JSON.

People building workflows with AI agents

Give an agent bounded SEO tools instead of asking it to improvise a crawler.

Local stdio MCP: no hosted account, inbound port or telemetry.
Accurate side-effect boundaries for network, files and paid providers.
Twenty-seven detailed skills for tool routing and evidence interpretation.

In-house SEO, engineering and agency teams

Share stable artifacts that developers, analysts and stakeholders can inspect.

Template-level findings, exact URLs and failed measurements remain visible.
Optional traffic, demand and SERP sources join technical evidence.
Docker and a single Python package make local and VPS runs reproducible.

Seven layers of one complete SEO workflow

Each layer has a clear job. An agent can combine them, preserve the raw outputs and build a review without pretending that a missing measurement is a clean result.

Crawl Audit & Task Backlog

Evaluate Screaming Frog exports against a 96-check registry, generate audit.json/audit.md and turn confirmed issues into a prioritized backlog.

Review metadata, indexability, canonicals, redirects, links, sitemaps, hreflang, images, page depth and crawl-derived heuristics at site scale.
Export mode works from existing CSV/XLSX files. Live mode can launch a separately installed, actively licensed Screaming Frog CLI.
audit.json, audit.md, tasks.json and tasks.md with skipped checks explained.

Live URL & Site Checks

Parse pages, inspect headers and robots.txt, follow redirects, validate links and hreflang, expand sitemaps and run a bounded site-audit pass over selected URLs.

Confirm what the site returns now instead of relying only on a stale crawl snapshot.
Ten site-level tools run once; three page-level tools run per selected sitemap URL, with explicit failures and a default 25-page limit.
A seohead.site-audit/1 document ready for analysis or report generation.

Schema.org & AI Search

Validate Schema.org vocabulary and rich-result readiness, build connected entity graphs, inspect AI crawler access, llms.txt, citability and social previews.

Separate valid markup, vendor eligibility, graph connectivity and editorial readiness.
Generate only facts visible on the page; no invented ratings, authors or prices.
Validation findings and a grounded connected JSON-LD graph proposal.

Domain & Infrastructure Recon

Profile DNS, RDAP, TLS, hosting, CDN cache behavior, technologies, security headers, mirror variants, regional structures and known backlink donors.

Find technical risks that an HTML crawler cannot measure reliably.
Every detection includes evidence and distinguishes unavailable data from absence.
A compact infrastructure profile with contradictions and verification steps.

Content, Media & Logs

Detect near-duplicates, compare raw and rendered DOM, analyze bot access logs, download media and optimize raster/SVG assets with safe file defaults.

Connect crawl symptoms with rendered content, real bot behavior and page-weight work.
Image rewrites are opt-in, validated and backed up; conversions retain the source.
Duplicate clusters, render/log evidence and before/after media reports.

Demand, SERP & Traffic Sources

Use Wordstat and async Yandex SERP, Arsenkin exact frequency, Yandex Metrika and DataForSEO Google data through one guarded provider layer.

Add demand and first-party behavior to technical evidence instead of guessing impact.
Paid calls are explicit and journalled; DataForSEO remains sandbox by default.
Structured keyword, SERP, counter-setup, traffic and spend records.

Agent Skill Library

Twenty detailed technical skills and seven broader SEO playbooks explain when to call tools, how to read outputs and where human approval is still required.

Standardize audits, reporting, Schema.org, GEO/AEO, research and content workflows.
Keep non-obvious safety, provider and implementation rules beside the code.
A reusable, English-language workflow library shipped in the repository.

Representative commands

47 tools behind one CLI and one MCP server

The complete list is generated by seohead --help and the MCP tool registry. These commands show how the layers combine in real work.

Bounded site evidenceRun selected sitemap-based live and infrastructure checks into one audit document.

CLIseohead site-audit --url …MCPseo_site_audit

Screaming Frog auditEvaluate existing Screaming Frog exports against the 96-check registry.

CLIseohead sf run --exports-dir …MCPsf_audit_run

Page parserMetadata, headings, text, links and JSON-LD.

CLIseohead parse --url …MCPseo_parse

Schema validatorVocabulary, rich-result and graph validation.

CLIseohead schema-check --url …MCPseo_schema_check

Schema graph builderGrounded connected JSON-LD proposal.

CLIseohead schema-build --url …MCPseo_schema_build

Infrastructure profileRDAP, DNS, hosting, TLS and risk flags.

CLIseohead domain-profile --domain …MCPseo_domain_profile

Render comparisonRaw HTML versus rendered DOM and lab timings.

CLIseohead render-check --url …MCPseo_render_check

Log analysisSearch/AI bot crawl behavior from access logs.

CLIseohead log-analyze --path …MCPseo_log_analyze

Image optimizerSafe compression, conversion and resizing.

CLIseohead images-optimize --output-dir …MCPseo_images_optimize

Keyword expansionYandex Wordstat demand expansion.

CLIseohead keywords-expand --phrase …MCPseo_keywords_expand

Metrika reportFirst-party behavior with setup context.

CLIseohead metrika-report --counter …MCPseo_metrika_report

Report builderXLSX, DOCX, CSV, Markdown or JSON.

CLIseohead report-build --audit …MCPseo_report_build

What the toolkit does — and what it does not

In the author's workflow, evidence collection and report scaffolding are often several times faster. That is an experience statement, not a universal benchmark. Network conditions, crawl scope, provider quotas and expert review still determine total time.

The source is public. Report reproducible bugs or propose focused capabilities on GitHub, or contact SEOHEAD by email for project and collaboration questions.

Product architecture

From evidence collection to a reviewed deliverable

The current 3.0 architecture keeps one Python core and two user interfaces.

Layer 01Shared Python core

Core tools do not know whether a human CLI or an MCP agent called them.

shipped

Layer 0296-check crawl analyzer

Screaming Frog exports become structured findings, summaries and tasks.

shipped

Layer 03Live and infrastructure evidence

URL, render, Schema.org, DNS, CDN, technology, security and log tools close crawl blind spots.

shipped

Layer 04Demand and first-party data

Optional provider tools add keywords, SERPs, counter setup, traffic and spend records.

shipped

Layer 05Workflow skills and reports

Detailed skills route tool calls; five report formats preserve the same evidence.

shipped

Layer 06Clean public release

One reviewed public history, English documentation, safety guardrails and reproducible CI.

3.0

Roadmap

What improves next

New work must add measurable evidence without weakening local-first safety or report honesty.

Public 3.0 baseline

Clean source boundary, English docs and skills, 458 offline tests, package/Docker/CI verification.

shipped

Evidence joins

Stronger joins between crawl templates, provider data and first-party performance.

in progress

Regression fixtures

More synthetic sites and edge cases for redirects, schemas, rendering and international SEO.

in progress

Community extensions

Focused tools and skills through reviewed GitHub issues and pull requests.

open

FAQ

Setup, scope, data and contribution

Installation and runtime

Yes. The CLI and stdio MCP server are local, open no inbound port and send no telemetry. Only requested website and provider calls use the network.

Python 3.10 or newer. One pip install resolves the core dependencies; rendering, clustering, reports and provider integrations are optional extras.

Clone the repository, create a virtual environment, install .[all], then run seohead --help. Start the agent interface with seohead mcp.

Run it locally

Clone, install, inspect

The package is installed from the public repository. One command resolves the selected Python extras.

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

A real crawl-to-backlog result

The repository ships a reproducible synthetic crawl fixture. Two Screaming Frog exports produce 18 issues across six URLs and 15 prioritized tasks, with exact sources, anchors and XPath retained.

seohead sf run \
  --exports-dir examples/exports \
  --out ./report \
  --tasks

The fixture contains no client data. It generates audit.json, audit.md, tasks.json and tasks.md; missing exports remain explicit skipped checks.

Connect the same tools over MCP

The same 47 tools are available through one stdio process. It opens no HTTP port and sends no telemetry.

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

Restart the MCP client and verify that it lists 42 seo_* tools and five sf_* tools.

Requirements and optional dependencies

Python 3.10+ for the CLI and local MCP server
An active paid Screaming Frog licence only for live SF CLI crawl mode; export analysis works without it
Playwright only for raw-versus-rendered checks
Your own credentials for optional providers; DataForSEO stays sandbox by default