网站SEO诊断 — crawl any website and report on-page, technical, and structured-data SEO issues. Zero config, no API keys, pure standard library.
Project description
🔍 website-seo-audit
Crawl any website and get a graded SEO report — in seconds, with zero setup.
English · 简体中文
A dependency-free SEO auditor you can run as a command-line tool or install as a skill for your AI coding agent (Claude Code, Codex, opencode, …). It crawls a site, checks dozens of on-page, technical, and structured-data signals, and hands you a scored report with a concrete fix for every issue.
No API keys. No sign-up. No pip install. Just Python 3.8+ and the standard library.
python3 -m seo_audit https://example.com
✨ See it in action
# 🔍 SEO Audit — https://example.com
Score: 72/100 (C) · 🔴 2 critical · 🟡 8 warnings · 🟢 15 notices
Crawled 23 pages · 45 internal links checked
## 🔴 Critical (2)
### Broken internal links (3×)
Internal link returns HTTP 404: https://example.com/old-page
- Fix: Fix or remove the link, or restore the target page (add a redirect if it moved).
### Site not on HTTPS
- Fix: Install a TLS certificate and redirect all HTTP traffic to HTTPS.
## 🟡 Warnings (8)
### Missing meta description (6×)
### Duplicate titles
### Structured data missing fields — Article missing image, datePublished
...
👉 Full example: examples/sample-report.md
🚀 Quick start
git clone https://github.com/zxhydfzr/website-seo-audit.git
cd website-seo-audit
python3 -m seo_audit https://yoursite.com
That's it. No virtualenv, no packages to install.
Prefer a global command? Install with pipx:
pipx install git+https://github.com/zxhydfzr/website-seo-audit.git
seo-audit https://yoursite.com
🤖 Use it inside your AI agent
This repo ships a SKILL.md, so any agent that supports the open
Agent Skills format can pick it up.
Then just say: "audit the SEO of https://example.com" and your agent runs the
tool and explains the results.
| Agent | Install |
|---|---|
| Claude Code | git clone https://github.com/zxhydfzr/website-seo-audit ~/.claude/skills/website-seo-audit |
| Codex | Clone into your project — the bundled AGENTS.md tells it how to run |
| opencode / others | Clone anywhere the agent can read files and point it at SKILL.md |
🔬 What it checks
|
On-page
|
Technical
|
Structured data ⭐
|
⭐ Why it's different
- Structured-data aware. Most quick SEO checkers stop at titles and headings. This one validates your JSON-LD / Schema.org markup — the signal search engines and AI answer engines use to understand and cite your pages.
- Zero dependencies. Only the Python standard library, so it runs anywhere Python does — laptops, CI, containers, a locked-down server.
- Agent-native. Ships as a portable skill, so your AI assistant can run a full audit and walk you through the fixes conversationally.
- Polite & safe. Respects
robots.txt, sends a real User-Agent, rate-limits itself, and only crawls the site you point it at.
⚙️ Options
| Option | Default | Meaning |
|---|---|---|
-1, --single |
off | Audit only the given URL (no crawl) |
--max-pages N |
50 | Max pages to crawl |
--max-depth N |
3 | Max crawl depth |
--json |
off | Machine-readable JSON output |
-o, --output FILE |
— | Write the report to a file |
--ignore-robots |
off | Crawl even if robots.txt disallows (your own sites) |
--no-link-check |
off | Skip broken-link detection (faster) |
-q, --quiet |
off | Suppress crawl progress |
The command exits non-zero when any critical issue is found, so you can gate CI:
seo-audit https://yoursite.com --json -o seo.json || echo "SEO regressions!"
📊 How the score works
Starts at 100 and deducts, with per-severity caps so a big site can't collapse on notices alone: 🔴 −15 each · 🟡 −3 each · 🟢 −1 each. Grades: A ≥90 · B ≥80 · C ≥70 · D ≥55 · F below.
🗺️ Roadmap
- Page-speed / Core Web Vitals signals
- hreflang & internationalization checks
- HTML report export
- Optional sitemap-seeded crawl (audit every listed URL)
Ideas and PRs welcome — see below.
🤝 Contributing
Issues and pull requests are very welcome. The codebase is small, typed, and dependency-free by design; please keep it that way. Run the tests with:
python -m unittest discover -s tests
🧭 Prior art & credits
website-seo-audit is written from scratch, with no third-party code — that's
the whole point of "zero dependencies." Its checks follow widely-published SEO
guidance (Google Search documentation and the best practices you'll find echoed
across the industry). If you're weighing options, two well-known open-source
tools cover nearby ground and are worth a look:
python-seo-analyzer and
seonaut.
Where this project puts its emphasis: zero dependencies, install-as-an- agent-skill packaging, and structured-data (JSON-LD / Schema.org) validation.
📄 License
MIT — free for personal and commercial use.
If this saved you time, a ⭐ helps others find it.
Made for everyone who wants clean SEO without a dashboard login.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file website_seo_audit-1.0.0.tar.gz.
File metadata
- Download URL: website_seo_audit-1.0.0.tar.gz
- Upload date:
- Size: 28.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5e714b215dc2f36772b02a7bf780344bc8c6ba0a36e9c025fddd649fdd04816c
|
|
| MD5 |
ec1944f339ef12615fda1576518f5ac0
|
|
| BLAKE2b-256 |
6705e3fcefa2e76ee11132580e3f3e4a98136b52ed818ad1b4ae4bb9e5db9e51
|
File details
Details for the file website_seo_audit-1.0.0-py3-none-any.whl.
File metadata
- Download URL: website_seo_audit-1.0.0-py3-none-any.whl
- Upload date:
- Size: 27.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a167e40b91955596a79321a410e5d41f665502802841116f042d1d3e925d00a4
|
|
| MD5 |
124f36a2774a5491b54db6f903b9b18e
|
|
| BLAKE2b-256 |
8fa869a7670a270345ab1dfe6b87578a62efa8d5357a982cdd446fcffacb114e
|
