From audit grind to predictable results

SEO Scripts — a CLI toolkit for SEO specialists

Eleven SEO tools on one Python core, available two ways: from the command line (the seohead CLI) and as an MCP server for AI agents like Claude. There is also a local HTTP API. No desktop app, no GUI — it runs anywhere Python runs. Open source on GitHub.

GitHubIssues
Who it is for

Who SEO Scripts actually saves time for

For people who care about speed, accuracy, and reproducibility: fewer manual errors across thousands of URLs and more time for strategy — without vague, half-manual pipelines.

SEO specialists and SEO leads

When you need to clear routine work fast and keep more time for strategy.

  • Repeatable tasks in a single command — scriptable and schedulable.
  • Faster first-pass checks and export prep for reports.
  • Pairs well with GA4 / GSC / Excel.

People working with AI agents

When you want to delegate SEO tasks to Claude or another MCP client.

  • Tools exposed to the agent over MCP: parsing, redirects, sitemap, media, clusters.
  • The agent calls the right tool and gets a structured result back.
  • Ships with ready-made SEO skills for Claude Code.

Webmasters and technical staff

When manageable files, clear artifacts, and control over technical changes matter.

  • Redirects, sitemap walks, HTML/meta/JSON-LD parsing without extra manual work.
  • Media download and optimization flows for releases.
  • Exports you can hand straight to dev or CI.

Eleven tools — one ecosystem for the SEO process

Each tool has a narrow job; together they form an end-to-end flow: one step's output often becomes the next step's input without manual copy-paste. Every tool can be called from the CLI or as an MCP command.

01

Redirect Builder

URL pairs → ready Apache/Nginx rules with 301/302, syntax for thousands of lines and typical-error checks; a separate command follows live redirect chains.

  • Migrations and URL changes without losing link equity: automation instead of hours of hand-writing rules.
  • A clean server config: fewer cycles, syntax errors, and URLs that sink after release.
  • Output: a redirect rules file ready for rollout and QA.

02

Image Optimizer

Compression and conversion to modern formats (WebP and more) for lighter pages; presets, resize, and backups via Sharp/SVGO.

  • Faster loading and more predictable performance metrics without hand-processing hundreds of files.
  • Batch asset prep before deploy: formats, sizes, and a before/after report in kilobytes.
  • Output: an optimized file set and a size comparison.

03

SEO Parser

Bulk collection of meta, H1–H6 headings, text, links, and JSON-LD — the base data layer for any audit; browser-like requests with gzip/brotli support.

  • The first audit stage in a short time instead of a manual crawl: a base for reports, tickets, and chaining with other tools.
  • A snapshot of what the page actually returns before and after release, without reading markup by hand.
  • Output: structured Markdown/JSON for the team and reporting.

04

Image Downloader

Bulk download from a URL list: correct extension by content-type, skips already-downloaded files, clear folder structure.

  • A bridge between parsing and optimization: grab media for an audit, competitor teardown, or visual capture.
  • A local mirror of assets in a clear structure for staging and further processing.
  • Output: a file catalog and a manifest for the next pipeline step.

05

Keyword Clusterer

Semantic query groups (K-Means, DBSCAN, Agglomerative) across tens of thousands of phrases — export to CSV/XLSX. Uses Python 3 + scikit-learn on the host.

  • From keyword chaos to topic clusters: IA, landing pages, and a content plan grounded in data, not intuition.
  • A map of meaning groups for catalog templates, filters, and dev prioritization.
  • Output: a cluster table for architecture and the editorial plan.

06

Prompt Library

Ready-made SEO skills and prompts for Claude Code: templates with variables for repeatable scenarios, shipped with the tool.

  • Faster drafts and checks with AI without scattered notes — a 'skills layer' on top of the tools.
  • Standard wording for specs, checklists, and tech notes for releases.
  • Output: a set of skills/prompts ready to plug into Claude Code or a wiki.

07

Sitemap Analyser

Recursive sitemap.xml parsing (index/urlset, gzip): a URL tree, duplicates, and a base for indexation checks.

  • Sitemap diagnostics: fewer stale and problem URLs in the hints you give the crawler.
  • Reconciling the sitemap generator with the real architecture and section priorities.
  • Output: MD/JSON for the report and dev tasks.
All commands

The full set: 11 tools, CLI and MCP

Every tool is one seohead command and an MCP tool for an AI agent.

SEO ParserMeta, headings, JSON-LD, links, text.
CLIseohead parse --url …MCPseo_parse
Redirect BuilderApache/Nginx rules from URL pairs.
CLIseohead redirects-generateMCPseo_redirects_generate
Redirect CheckerFollow a live redirect chain.
CLIseohead redirects-check --url …MCPseo_redirects_check
Sitemap AnalyserParse sitemap (index/urlset, gzip).
CLIseohead sitemap-crawl --url …MCPseo_sitemap_crawl
Image DownloaderBulk download from a URL list.
CLIseohead images-downloadMCPseo_images_download
Image OptimizerCompress/convert JPG/PNG/WebP/SVG.
CLIseohead images-optimizeMCPseo_images_optimize
Keyword ClustererKeyword clusters (K-Means/DBSCAN).
CLIseohead keywords-clusterMCPseo_keywords_cluster
Robots Analyserrobots.txt: rules, sitemaps, allow checks.
CLIseohead robots-check --url …MCPseo_robots_check
Header InspectorSEO response headers, HTTP version, TTFB.
CLIseohead headers-check --url …MCPseo_headers_check
Link CheckerBroken links and links to redirects.
CLIseohead links-check --url …MCPseo_links_check
hreflang ValidatorExtract and validate hreflang.
CLIseohead hreflang-check --url …MCPseo_hreflang_check

Important

SEO Scripts is developed with active use of AI tools: drafting logic, speeding up refactoring, preparing documentation. Final decisions go through manual review, but the project stays alive and keeps improving.

The tool is published 'as is'. You can fork the repository, open a PR, or message me on LinkedIn — I'll gladly look at ideas and discuss what to add in the next updates.

Development stages

Development stages and what is already shipped

Iterations from separate scripts to a single core and headless launch: collect → process → export artifacts for the team and AI agents.

Stage 01Platform-independent core

Tool logic moved into a shared TypeScript module independent of how it is launched, with lint and tests.

done
Stage 02Redirect and media tools

Redirect Builder and the image-processing block were added for bulk operations.

done
Stage 03Parsing and sitemap walk

SEO Parser and Sitemap Analyser were added with exportable results for audits.

done
Stage 04Clustering and skills library

The semantic module and a set of SEO skills/prompts for Claude Code joined the shared toolkit.

done
Stage 05Headless pivot: CLI + MCP + HTTP

We removed the desktop GUI, kept the core, and wrapped it in the seohead CLI, an MCP server for AI, and a local HTTP API.

done
Stage 06Stabilization and edge cases

Current focus — reliability on non-standard URLs and formats, export accuracy, and smooth calls from scripts and agents.

in progress
Roadmap

What is planned next

A public plan for the coming iterations. Priorities may shift based on feedback and bug reports from real projects.

CLI and flag ergonomics

Clearer output, consistent flags, friendly errors for running from scripts and schedulers.

in progress

Tech stability and edge cases

More coverage for non-standard URLs, file formats, timeouts, and export errors.

in progress

A pack of per-tool guides

A series of blog teardowns: 'how to use tool X in a real SEO process'.

planned

Community contribution

Issue templates and proposals for new tools via GitHub Issues/PR.

open
FAQ

Answers by category: setup, tools, data, open source

Installation and runtime
Yes. The CLI and MCP server run locally with no mandatory cloud dependency — only the tools that hit the web (parsing, sitemap crawl) need a connection.
Python is only needed for the Keyword Clusterer tool. Everything else runs on Node.js alone.
Clone the repository, run npm install and npm run build, then node out/cli.js --help. Try parse and redirects-generate first for a fast functional check. To use it from Claude, run npm run mcp.
Deployment

Quick start from the repository

Run, test, or extend the tool locally. Commands are available via the seohead binary after installing the package:

pip install "seohead-scripts[all]"
seohead --help

# Example: parse a page
seohead parse --url https://example.com

Keyword Clusterer — Python

Clustering runs in an external Python worker: you need a Python interpreter, an isolated environment, and a reproducible set of library versions. The commands below are for macOS/Linux; on Windows activate the environment with .venv\Scripts\activate.

python3 -m venv .venv
source .venv/bin/activate
pip install scikit-learn numpy nltk
pip freeze > requirements-clusterer.txt
python -m nltk.downloader stopwords

Attach requirements-clusterer.txt or explicit version pins to the task: without them another machine gives a different result. Make sure SEO Scripts sees the right Python (PATH in the user session).

MCP server and HTTP API

The same tool can run as an MCP server for AI agents (Claude and any MCP client) or as a local HTTP API:

# MCP server over stdio — for Claude and other MCP clients
seohead mcp

# Local HTTP API over the core
seohead serve

To connect to Claude Code, add the MCP server to the client config (launch command — seohead mcp). The tools become available to the agent as MCP commands: parsing, redirects, sitemap, robots.txt, headers, links, hreflang, media, clustering.

Technical requirements

  • Python 3.10+ — for the CLI, MCP server, and HTTP API
  • The 'cluster' extra (scikit-learn) — only for the Keyword Clusterer tool
  • Cross-platform: runs on macOS, Linux, and Windows