SEO Tools

Local-first technical SEO audit automation

Turn crawl data into a clear fix list.

Collect the evidence, find technical SEO issues and hand over a report your team can work from. SEOHEAD runs locally through Python, CLI and MCP, with the source and the limits of each check visible.

See a real auditView on GitHub

Open source · MIT-licensed Python code · No hosted account required

Local
Your files stay with you
Run on your computer, in Docker or on a server.
CLI + MCP
One set of tools
Use commands directly or connect an AI agent.
XLSX + JSON
Readable and reusable
Share the report and keep the structured evidence.
Open source
Inspect and adapt
MIT-licensed Python code, tests and workflow guides.
Real output · seohead.tech

A real audit of this website

Open the report produced by SEOHEAD on 9 September 2026. These are previews of its actual Excel sheets, with columns fitted for readability. Select an image to inspect it at full size.

Download Excel reportAudit data and tasks

01 / Start with the summary

See the number of URLs, severity of findings and checks that were unavailable. This run found no critical issues in the checks it could evaluate.

02 / Follow each finding to its URL

The Findings sheet records severity, source, affected URL and recommendation. Automated thresholds and template-wide notices need context before implementation.

03 / Inspect the pages behind the report

The Pages sheet preserves per-URL measurements. Use it to investigate an individual finding and keep the original crawl evidence available to the team.

An example you can inspect

What comes out of an audit

An issue, a check and a task are different things. One check can find several issues; related findings become a single task for the team.

The same crawl, three useful outputs

seohead.tech, 9 September 2026, before this page refresh. A native HTML crawl finished within a 400-URL limit, respecting robots.txt at one URL per second. The workbook contains automated flags for specialist review.

  1. 355URLs fetched

    354 HTML pages, including 350 indexable pages.

  2. 1,334automated findings

    36 warnings and 1,298 notices. Repeated template flags need review.

  3. 24grouped tasks

    A separate JSON and Markdown backlog to inspect and assign.

Critical: 12 of 161Warning: 75 of 161Notice: 74 of 161161checks

What could this run check?

This snapshot used the 161-check registry at toolkit commit f6a3222. It evaluated 128 checks; 33 lacked the required evidence. Browser rendering, resource fetches and external provider data were outside this crawl. A score from incomplete coverage is not comparable with a full-evidence run.

  • 12 critical
  • 75 warning
  • 74 notice
checks with findings: 24 of 161checks without findings: 104 of 161checks not evaluated: 33 of 16124of 161 fired

Which checks ran, and which could not?

24 checks with findings
These checks reported at least one issue. A check can report multiple issues.
104 checks without findings
These checks ran and reported no issues for the supplied data.
33 checks not evaluated
Required evidence was unavailable. These checks are not reported as passed.

Checks in this registry: 161

Each bar is one topic. The darker the segment, the more serious the finding it produces.

  1. Links & internal graph2 critical13 warning10 notice25
  2. Titles, descriptions, headings1 critical9 warning15 notice25
  3. Content quality9 warning8 notice17
  4. Indexability & directives1 critical5 warning7 notice13
  5. HTML validity & rendering5 warning7 notice12
  6. Sitemaps1 critical6 warning4 notice11
  7. Hreflang & international9 warning1 notice10
  8. URL hygiene2 warning8 notice10
  9. Canonicals1 critical5 warning3 notice9
  10. Page weight & speed3 warning4 notice7
  11. Security & transport2 critical3 warning2 notice7
  12. Redirects & status codes4 critical1 warning1 notice6
  13. Images & media3 warning2 notice5
  14. Structured data & social2 warning2 notice4

Open the source data for this example

01

Crawl collection and analysis

Analyze Screaming Frog exports or collect pages with the native crawler. Turn the supported evidence into findings and a prioritized backlog.

Audit findings and prioritized tasks, with unavailable checks listed.

02

Live page 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.

A seohead.site-audit/1 document ready for analysis or report generation.

03

Structured data and AI search

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

Validation findings and a grounded connected JSON-LD graph proposal.

04

Domain and infrastructure

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

A compact infrastructure profile with contradictions and verification steps.

05

Content, media and logs

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

Duplicate clusters, render/log evidence and before/after media reports.

06

Demand, search results and traffic

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

Structured keyword, SERP, counter-setup, traffic and spend records.

07

Agent workflow skills

Detailed technical and SEO playbooks explain when to call tools, how to read outputs and where specialist review is still required.

Reusable workflow guides shipped with the repository.

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.
  • Detailed workflow guides 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.
Representative commands

From a task to the right command

These examples show the shape of common workflows. Run seohead --help for the current command list and use the command-specific help for all required options.

TaskCLIMCP
Native bounded crawlCrawl without a Screaming Frog licence into an audit or a SQLite artifact.seohead crawl-site --url …seo_crawl_site
Bounded site evidenceRun selected sitemap-based live and infrastructure checks into one audit document.seohead site-audit --url …seo_site_audit
Screaming Frog auditEvaluate existing Screaming Frog exports against the 161-check registry.seohead sf run --exports-dir …sf_audit_run
Before / after diffPer-check diff of two crawls: what appeared, what disappeared, what was actually fixed.seohead compare-crawls --before … --after …seo_compare_crawls
Page parserMetadata, headings, text, links and JSON-LD.seohead parse --url …seo_parse
Schema validatorVocabulary, rich-result and graph validation.seohead schema-check --url …seo_schema_check
Schema graph builderGrounded connected JSON-LD proposal.seohead schema-build --url …seo_schema_build
Infrastructure profileRDAP, DNS, hosting, TLS and risk flags.seohead domain-profile --domain …seo_domain_profile
Render comparisonRaw HTML versus rendered DOM and lab timings.seohead render-check --url …seo_render_check
Log analysisSearch/AI bot crawl behavior from access logs.seohead log-analyze --path …seo_log_analyze
Image optimizerSafe compression, conversion and resizing.seohead images-optimize --files image.png --output-dir optimizedseo_images_optimize
Keyword expansionYandex Wordstat demand expansion.seohead keywords-expand --phrase …seo_keywords_expand
Metrika reportFirst-party behavior with setup context.seohead metrika-report --counter 123 --metrics ym:s:visitsseo_metrika_report
Report builderXLSX, DOCX, CSV, Markdown or JSON from the same audit document.seohead report-build --audit …seo_report_build
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/seotools.git
cd seotools
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[all]"
seohead --help

Requirements and optional dependencies

  • Python 3.10+ for the CLI and local MCP server
  • No Screaming Frog licence is required: the native crawl-site command feeds the same registry
  • 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

Connect the same tools over MCP

Connect the local stdio MCP server to your client. It uses the same tool handlers as the CLI and opens no inbound HTTP port.

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

Use the absolute path to your virtual environment, restart the MCP client and inspect the available tools.

A real crawl-to-backlog result

Try the synthetic Screaming Frog exports included in the repository. The command writes findings, coverage details and a prioritized task list without crawling a website.

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

The fixture contains no client data. Inspect the generated report for available evidence and named skipped checks.

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.
Yes. The crawl-site command collects public pages directly and feeds the audit registry. Checks whose required evidence is unavailable are listed as skipped with a reason.
Yes for supported saved inputs: audit existing Screaming Frog exports and reopen supported SQLite scans without fetching the site again. Live checks, crawling and provider calls require a network connection.
Use the Python CLI or the Docker setup in the repository. Commands accept explicit options and write structured output; no graphical interface is required.

Start with the source

Public source code

Install, inspect and adapt the Python toolkit.

Open GitHub

Current tool reference

Available commands, arguments and side effects generated from the tool registry.

Read the tool reference

Workflows and examples

Choose a specialist task and follow its tool chain to a usable artifact.

Explore the scenarios

What the toolkit does — and what it does not

The toolkit collects and organizes evidence. A specialist still decides which findings matter, checks recommendations against the business context and verifies the implementation. Crawl scope, network conditions and available inputs affect the result.

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