MCP SEO Auditor

MCP SEO Auditor

Free on-page SEO audits from Claude Code or Cursor — find broken titles, missing meta descriptions, canonical issues, robots conflicts, and JSON-LD errors before your pages go live. Fully local, no API keys.

Part of the [petrovicistefan MCP suite](https://github.com/petrovicistefan/mcp-marketplace) — local-first guardrails for AI coding agents.

---

Quick Install

Requirements: Python 3.11+ and Node.js 18+

Cursor

Or use the deeplink directly:

cursor://anysphere.cursor-deeplink/mcp/install?name=mcp-seo-auditor&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1zZW8tYXVkaXRvciJdfQo=

Or add manually to ~/.cursor/mcp.json:

{

"mcpServers": { "mcp-seo-auditor": { "command": "npx", "args": ["-y", "mcp-seo-auditor"] } } }

Claude Code

claude mcp add mcp-seo-auditor -- npx -y mcp-seo-auditor

If this server is on Claude MCP Marketplace:

/plugin marketplace add petrovicistefan/mcp-marketplace

Claude Desktop

Add to claude_desktop_config.json:

{

"mcpServers": { "mcp-seo-auditor": { "command": "npx", "args": ["-y", "mcp-seo-auditor"] } } }

VS Code

Use the MCP install link, or add to .vscode/mcp.json:

{

"servers": { "mcp-seo-auditor": { "type": "stdio", "command": "npx", "args": ["-y", "mcp-seo-auditor"] } } }

npx (any MCP client)

npx -y mcp-seo-auditor

uvx (PyPI, coming soon)

uvx mcp-seo-auditor

*PyPI package not yet published. See PyPI Publishing below.*

---

Other MCP clients (Windsurf, Cline, Zed, Gemini CLI, Codex CLI)

Codex CLI

codex mcp add mcp-seo-auditor -- npx -y mcp-seo-auditor

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{

"mcpServers": { "mcp-seo-auditor": { "command": "npx", "args": ["-y", "mcp-seo-auditor"] } } }

Zed

Add to settings.json:

{

"context_servers": { "mcp-seo-auditor": { "command": "npx", "args": ["-y", "mcp-seo-auditor"] } } }

Gemini CLI

Add to ~/.gemini/settings.json:

{

"mcpServers": { "mcp-seo-auditor": { "command": "npx", "args": ["-y", "mcp-seo-auditor"] } } }

---

⭐ Found this useful? [Star this repository](https://github.com/petrovicistefan/mcp-seo-auditor) to help others discover it!

---

Why MCP SEO Auditor?

Catch SEO issues before you deploy by asking your AI coding assistant to audit your HTML:

• "Audit this page before I push it" — find missing titles, broken meta descriptions, or canonical conflicts
• "Crawl example.com and check for duplicate titles" — spot content duplication across your site
• "What SEO issues does this HTML have?" — get actionable recommendations with severity levels

Unlike hosted SEO tools that require API keys, cloud accounts, and monthly fees, MCP SEO Auditor runs entirely on your machine. No data leaves your computer unless you explicitly crawl a public URL.

Tools

MCP SEO Auditor exposes 3 MCP tools your AI agent can call:

What Gets Checked

Each audit scans for:

• Title: presence, length (50–60 chars recommended), uniqueness
• Meta description: presence, length (150–160 chars recommended), uniqueness
• H1 headings: presence, count (multiple H1s flagged as informational)
• Canonical URL: presence, validity, self-referencing vs cross-domain
• Robots directives: conflicts (e.g., noindex + canonical)
• Language declaration: presence
• Viewport: mobile-friendly tag
• Image alt attributes: presence check (empty alt is valid for decorative images)
• JSON-LD structured data: JSON syntax validation
• Internal/external link inventory: counts for context

Output: Findings with severity (error, warning, info), issue codes, evidence snippets, and actionable recommendations. Plus a local checklist score (not a ranking forecast).

Use Cases

Individual Developers

"Audit the homepage HTML in index.html and prioritize the fixes."

"Check https://staging.example.com for SEO issues before I merge this PR." "Does this landing page have a proper canonical tag?"

Before Deployment

"Audit all HTML files in dist/ and list any errors."

"Crawl the staging site and find duplicate meta descriptions."

Content Review

"What's the title and description for this blog post HTML?"

"Does this page have structured data errors?"

Site Audits

"Crawl 10 pages starting at https://example.com and report duplicate titles."

"Which pages are missing H1 tags?"

Comparison with Alternatives

How does MCP SEO Auditor compare to other SEO tools for AI agents?

When to use MCP SEO Auditor: You want instant, zero-setup on-page audits of local HTML files or staging sites without external API dependencies.

When to use alternatives: You need live Google Search Console data, rank tracking, backlink analysis, or keyword research — those tools excel at connecting your agent to external SEO data sources.

Table of Contents

• Quick Start
• Why MCP SEO Auditor?
• Features
• Use Cases
• Comparison with Alternatives
• Requirements
• Installation
• From npm
• From a Checkout
• Tools Reference
• Boundaries and Security
• Limitations
• Hosted Path (Quotas via Control Plane)
• Product Direction
• Testing and Validation
• References
• More MCP Servers by the Author
• Contributing
• FAQ
• License

Requirements

• Python 3.11+ on PATH (defaults to python3 executable)
• Node.js 18+ (for the npm wrapper)

If python3 is not available or you need a specific Python executable, set the MCP_SEO_PYTHON environment variable to an absolute path.

Installation

From npm

The quickstart examples use npx -y mcp-seo-auditor which downloads and runs the package on demand. For persistent installations, add the MCP server to your client's configuration as shown in the Quick Start section.

From a Checkout

Clone the repository and run tests:

git clone https://github.com/petrovicistefan/mcp-seo-auditor.git

cd mcp-seo-auditor npm test

Run the server directly:

node bin/mcp-seo-auditor.mjs

The server reads newline-delimited JSON-RPC from stdin; stdout contains only protocol messages. It waits for an MCP client when started directly.

Register with Claude Code (replace with your absolute path):

claude mcp add seo-auditor -- node /absolute/path/mcp-seo-auditor/bin/mcp-seo-auditor.mjs

Or add to any MCP client config:

{

"mcpServers": { "seo-auditor": { "command": "node", "args": ["/absolute/path/mcp-seo-auditor/bin/mcp-seo-auditor.mjs"] } } }

Install the Python package directly (optional):

pip install .

mcp-seo-auditor

Build-time setuptools is needed; runtime uses only stdlib.

PyPI Publishing

This package is configured for PyPI Trusted Publishing (OIDC) but not yet published. The maintainer must complete a one-time setup at https://pypi.org/manage/account/publishing/:

• PyPI Project Name: mcp-seo-auditor
• Owner: petrovicistefan
• Repository name: mcp-seo-auditor
• Workflow name: publish-pypi.yml
• Environment name: (leave blank)

After setup, pushing a version tag (e.g., v0.1.3) will automatically publish to PyPI via the .github/workflows/publish-pypi.yml workflow.

Tools Reference

audit_html

Inputs:

• html (string, required, max 2 MB): The HTML content to audit
• url (string, optional): Base URL for resolving relative links

Output: JSON with findings, metadata, score, and link inventory

Example:

"Audit this HTML and tell me what's wrong: <html>...</html>"

audit_url

Inputs:

• url (string, required): Public HTTP(S) URL to fetch and audit

Output: Same as audit_html, plus http object with status, redirects, and elapsedMs

Example:

"Audit https://example.com and prioritize the issues."

Respects `robo