seo-audit-mcp

Ein MCP-Server, der Claude (oder jedem MCP-Client) die Möglichkeit gibt, das technische SEO einer Live-Website zu prüfen: Sitemap-Abdeckung, Probleme pro Seite und Weiterleitungsketten.

Frag in einfacher Sprache – „auditiere mortgagecalculatortools.com und sag mir, von welchen Seiten Google nie erfährt" – und das Modell ruft die Tools auf, durchsucht die Website und antwortet mit Details.

Das Problem, das es löst

Über die sitemap.xml einer Website teilst du Google mit, welche Seiten existieren. Wenn eine Seite darin fehlt, gibt es keinen Fehler und keine Warnung – die Seite sammelt einfach nie Impressionen. Die manuelle Prüfung bedeutet, ein Dateisystem-Verzeichnis gegen eine XML-Datei zu diffen, daher macht das in der Praxis niemand.

Fallstudie: Eine Lücke von 25 Seiten, die sich als richtig erwies

Die erste Website, auf die das Tool gerichtet wurde, hatte 125 HTML-Dateien auf der Festplatte und 100 URLs in ihrer Sitemap. Eine Lücke von 25 Seiten – die Art von Befund, der als Bug aufgeschrieben und jemandem zugewiesen wird.

Ein sitemap_coverage-Aufruf deckte die Lücke auf, und ein audit_urls-Aufruf an einer Stichprobe erklärte sie: Jede der 25 Seiten trug <meta name="robots" content="noindex, follow">. Es handelte sich um zwei bewusst von der Indizierung ausgenommene Inhaltscluster, und die Sitemap hatte genau richtig gehandelt, sie wegzulassen. Anschließend gegen das Dateisystem verifiziert: 25 noindex-Seiten auf der Festplatte, dieselben 25 fehlen in der Sitemap, null noindex-Seiten fälschlich enthalten. Perfekte Konsistenz.

Das ist das nützliche Ergebnis. Eine reine Abdeckungszahl („125 vs. 100") wirkt wie ein Defekt und kostet jemanden einen ganzen Tag; Abdeckung plus noindex-Status pro Seite beantwortet die Frage in einer Minute. Dieses Tool ist genauso wertvoll für die Fehlalarme, die es verhindert, wie für die echten Lücken, die es findet – deshalb meldet audit_urls noindex pro Seite und zählt nicht nur URLs.

Tools

Jedes Tool gibt strukturiertes JSON mit einer issues-Liste pro Seite und einer aggregierten issue_summary zurück, sodass das Modell über Zahlen nachdenken kann, statt rohes HTML erneut zu lesen.

Installation

pip install -e .

Erfordert Python 3.10+. Abhängigkeiten: mcp>=2.0.0, httpx.

Verbinde es mit Claude Code

Füge es zu .mcp.json in deinem Projekt hinzu (oder ~/.claude.json für die globale Nutzung):

{
  "mcpServers": {
    "seo-audit": {
      "command": "python",
      "args": ["-m", "seo_audit_mcp"]
    }
  }
}

Für Claude Desktop kommt derselbe Block in claude_desktop_config.json.

Dann frag einfach:

Rufe die Sitemap für https://example.com/sitemap.xml ab, prüfe die ersten 20 URLs und fasse die Probleme nach Häufigkeit zusammen.

Direkt ausführen

python -m seo_audit_mcp        # stdio transport

Design-Anmerkungen

Drei Entscheidungen, die hervorzuheben sind, weil sie den Unterschied zwischen einer Demo und etwas ausmachen, das man auf der Produktionswebsite eines Kunden einsetzen kann:

Das Crawling ist konstruktionsbedingt ratenbegrenzt. fetch_many läuft hinter einem asyncio.Semaphore, das auf 16 gleichzeitige Anfragen begrenzt ist, und jedes Tool begrenzt seine Eingaben. Eine Sitemap mit 500 URLs würde ohne diese Obergrenze 500 Sockets auf einmal öffnen und wie ein Angriff auf den Zielhost wirken. Das Crawling ist eine Last, die die Ziel- Website trägt, daher ist die Obergrenze von der Tool-Oberfläche aus nicht nach oben konfigurierbar.

Kein Abruffehler bricht einen Lauf ab. fetch_one fängt httpx.HTTPError ab und zeichnet ihn auf dem zurückgegebenen PageAudit auf, anstatt ihn auszulösen. Ein toter Host in einem Crawl mit 200 URLs verschlechtert eine Zeile, anstatt 199 gute Ergebnisse zu verlieren.

Das Parsing ist bewusst tolerant. Echtes HTML ist häufig fehlerhaft genug, dass ein strenger Parser, der mitten im Crawl eine Ausnahme auslöst, ein Risiko darstellt. Die Extraktoren sind großzügige Regexe, die None zurückgeben, anstatt zu werfen – aber mit behobenen Fallstricken: <script>- und <style>-Inhalte werden vor der Wortzählung und Heading-Extraktion entfernt, sodass ein <h1> in einem JS-String-Literal nicht als Überschrift gezählt wird, und relative Canonicals werden gegen die Seiten-URL aufgelöst.

normalize_url entfernt bewusst keine abschließenden Schrägstriche: /a und /a/ können tatsächlich verschiedene Seiten sein, und ihre Zusammenlegung würde Duplicate-Content-Probleme verbergen, die dieses Tool aufdecken soll.

Tests

pip install -e ".[dev]"
pytest

Die Suite ist netzwerkfrei – HTTP wird über httpx.MockTransport getestet, sodass sie in CI und im Flugzeug läuft. Sie deckt die Parsing-Grenzfälle ab, die in der Produktion beißen: in Skripten eingebettete Überschriften, Sitemaps ohne Namespace, relative Canonicals, Sitemap-URLs, die ein gestyltes HTML-404 mit einem 200-Status zurückgeben, und Nicht-HTML-Inhaltstypen, die fälschlich als Seiten „ohne Titel" gemeldet werden.

Lizenz

MIT