lv24-seo-optimizer

Free-first SEO control plane for humans and AI agents.

Your site's SEO, without a dashboard. Pull Search Console, Yandex Webmaster and Metrika, Bing, CrUX and your own crawl into one history — then get a weekly diff by email, an MCP server and a CLI that agents can actually use. No paid platform, no SERP scraping, no vendor account.

One tool that pulls Google Search Console, Yandex Webmaster, Yandex Metrika, Bing Webmaster, Chrome UX Report and PageSpeed Insights into a single normalized model, crawls your site for technical SEO regressions, and turns all of it into scheduled email reports, MCP tools, CLI commands and agent skills.

No paid SEO platform required. Everything in the default path has a free tier.

┌──────────── data sources (free) ────────────┐      ┌──── surfaces ────┐
│ GSC · Yandex Webmaster · Metrika · Bing ·    │ ───▶ │ CLI (--json)     │
│ CrUX · PSI · your own crawl + nginx logs     │      │ MCP server       │
└──────────────────────────────────────────────┘      │ Skills / AGENTS  │
                                                      │ Email / Telegram │
                                                      │ SQLite history   │
                                                      └──────────────────┘

Why another SEO tool

• Free-first fusion. Existing MCP servers wrap one vendor each and hand raw vendor shapes to the model. We join GSC + Bing + Yandex + Metrika per property, and we say out loud what the APIs cannot give you (Yandex has no query×page join, GSC caps at 50k rows/day, data lags 2–3 days). Every response carries truncated, total, data_age and limitations[].
• Diffs, not dashboards. Reports compare against the last stored snapshot and only email you when something material changed (traffic drop, new indexing errors, sitemap regressions, TLS expiry).
• Agent-native. A small, stable MCP tool surface (read-only by default), a JSON envelope on every CLI command, and skills that encode audit → plan → fix → verify against a real repository.
• Zero spend. Public-repo CI, SQLite storage, SMTP/Telegram delivery, no SaaS in the default path. Paid providers (Ahrefs, Semrush, DataForSEO, SerpApi) are optional adapters that use your key.

Status

Alpha (v0.1.0 in progress). Working today: six provider adapters (GSC, Yandex Webmaster, Yandex Metrika, Bing/IndexNow, CrUX, PSI), a 30-rule crawler, SQLite history, analysis (deltas, opportunities, indexing triage, multi-engine fusion, nginx log stats), report builders + HTML/text/Markdown renderers, SMTP/Telegram delivery with idempotency, the full CLI, the MCP server (10 tools, 3 resources, 3 prompts) and scheduler generators.

Still missing before v0.1.0 is declared stable: GSC service-account auth (OAuth token only today), write operations for sitemap/recrawl (IndexNow is wired; the others return an honest WRITE_DISABLED), and an end-to-end run against a live property. See docs/plans/2026-11-10-implementation-plan.md for the wave status.

Install

# Python (recommended)
uvx --from lv24-seo lv24-seo doctor
pipx install lv24-seo                 # or: uv tool install lv24-seo

# Node users: thin launcher over the same CLI
npx @lv24/seo doctor --json

lv24-seo init --property https://example.com   # writes seo.toml + data/
lv24-seo auth set --provider gsc --stdin       # token in the OS keychain
lv24-seo report weekly --json --out reports/
lv24-seo mcp serve                             # stdio MCP server
lv24-seo install --client claude|opencode|vscode|cursor

npx @lv24/seo requires uv (or an installed lv24-seo binary): the npm package is a launcher, not a second implementation.

See it work

$ lv24-seo doctor

[OK  ] python: 3.13.12
[OK  ] platform: Windows 11
[OK  ] config: C:\work\seo.toml
[OK  ] cwd_writable: C:\work
[FAIL] tokens: not configured yet (gsc / yandex / metrika / bing / crux)

$ lv24-seo report weekly --days 7 --json --out reports/

# headline   clicks +18.2%, impressions +6.4%, position -1.1
# traffic    gsc 1 240 clicks · yandex 310 · metrika 92 sessions
# indexing   3 new "crawled - not indexed" URLs, 0 regressions
# actions    5 opportunities, expected +41 clicks/week
# honesty    data_age_days=2, yandex: top_3000_queries, no_query_page_join

The same data is available as MCP tools (seo_weekly_report, gsc_search_analytics, yandex_query_stats, seo_indexing_triage, …) and as three skills that encode audit → plan → fix → verify.

What it will do

Supported sources

Documents

• Implementation plan — waves, work packages, DoD
• Architecture — layers, data model, provider contracts
• Data sources & limits — what each API can and cannot do
• MCP tool surface — tool names, inputs, outputs, annotations
• CLI reference — commands, JSON envelope, exit codes
• Configuration — seo.toml, env vars, secret storage
• Scheduling & delivery — cron/systemd/Task Scheduler, SMTP, Telegram
• Agent skills — skill format and mirrors
• Security — token handling, read-only defaults, write gating
• Research 2026 — API limits, existing MCP servers, tool landscape

For AI agents

Read AGENTS.md first. It is the canonical contract: repo layout, how to run things, what is read-only, how to propose a change. Machine-readable helpers:

• schemas/tools.json — generated tool schemas (works without MCP)
• llms.txt — doc map for LLM crawlers
• skills/*/SKILL.md — portable skills (Claude Code, OpenCode, Codex)
• MCP Registry: io.github.LevapVeeskela/lv24-seo

License

Apache-2.0. See LICENSE and TRADEMARKS.md. Data pulled from Google/Yandex/Bing belongs to the property owner — this project never resells it.