MCP SEO Auditor

io.github.petrovicistefanv0.1.1Updated Oct 9, 2026

Read-only static SEO audits and bounded crawling for AI agents.

VerifiedSTDIODesktop onlyDeveloper ToolsWeb Search & Scraping

Overview

AI-generated overview

Runs read-only static SEO audits on HTML or a URL and crawls up to ten same-origin pages, reporting issues with severity and fixes.

What it does
The server exposes three tools: audit_html for static checks on supplied markup without network access, audit_url for a page audit plus HTTP status, redirects and elapsed request time, and crawl_site for same-origin audits with duplicate title and description detection. Checks cover title, meta description, H1, canonical, robots/noindex, language, viewport, image alt presence, link inventory and JSON-LD syntax. Reports include issue codes, severity, evidence and recommendations.
When to use it
Use it when an assistant should review a page or a small site for on-page SEO basics before deployment, or when triaging duplicate titles and descriptions across a handful of pages. It suits static HTML review rather than rendered single-page applications.
Requirements
Runs locally over stdio as an npm package (npx -y mcp-seo-auditor) and needs Node.js plus Python 3.11+ on PATH; MCP_SEO_PYTHON can point to an absolute Python executable. No account, API key or telemetry. Network access is needed only for audit_url and crawl_site. A separate hosted HTTP path exists and requires a bearer token.
Before you install
Audited page content is untrusted and should never be treated as instructions. Static HTML only, so JavaScript-rendered pages can yield findings that disappear after rendering. Crawling is bounded and robots.txt is checked; credentials in URLs are rejected. The score is a local checklist, not a ranking forecast, and it does not cover backlinks, Search Console, rich results, broken links or Core Web Vitals.

Installation

In SourceWeft

  1. Open MCP SEO Auditor in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

MCP SEO Auditor

Read-only SEO tools for Claude Code, Cursor and other MCP clients. Audits run locally. No API keys, telemetry, AI-provider costs or runtime dependencies.

MVP 0.1.0. Node wrapper requires Python 3.11+ (python3, or set MCP_SEO_PYTHON to an absolute executable path).

Install in your AI client

Requires Python 3.11+ on PATH in addition to Node.js. Works with any MCP client over stdio; no account or API key needed for the local server.

Claude Code

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

Codex CLI

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

Claude Desktop, Cursor, Windsurf, Cline, Gemini CLI — add to the client's MCP config (claude_desktop_config.json, ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, Cline MCP settings, ~/.gemini/settings.json):

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

VS Code / GitHub Copilot — .vscode/mcp.json:

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

Zed — settings.json:

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

Run from a checkout

sh
npm testnode 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.

Claude Code registration (replace path):

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

Generic MCP configuration:

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

Alternatively install Python package with pip install . and run mcp-seo-auditor. Build-time setuptools is needed; runtime uses only stdlib.

Configuration can use npx -y mcp-seo-auditor.

Tools

ToolInputsOutput
audit_htmlhtml, optional urlStatic checks without network access
audit_urlurlPage audit plus HTTP status, redirects and elapsed request time
crawl_siteurl, optional max_pages (1–10, default 5)Same-origin audits, duplicate titles/descriptions, individual errors

Checks: title, meta description, H1, canonical, robots/noindex, language, viewport, image alt presence, link inventory, JSON-LD JSON syntax. Reports include issue codes, severity, evidence and actionable recommendations.

Example agent requests:

  • “Audit https://example.com/ and prioritize the fixes.”
  • “Crawl 10 pages and find duplicate titles.”
  • “Audit this HTML before I deploy it.”

Boundaries and security

  • Static HTML only; no browser or JavaScript execution. SPA output can produce findings that disappear after rendering.
  • HTTP(S), conventional ports only. Credentials in URLs are rejected. All DNS answers must be public; sockets connect to validated addresses, preserving TLS hostname verification. Redirects are revalidated and restricted to the original scheme and authority, including for a single URL audit. Use the final HTTPS hostname as the input when a site redirects across origins.
  • robots.txt is checked before network page audits and every redirected page. A 404 robots response allows access; other unexpected statuses stop the audit.
  • 2 MB response limit, 10-second socket inactivity timeout, five redirect hops, at most 10 attempted crawl URLs, minimum 200 ms crawl interval and 90-second crawl loop budget (an in-flight fetch may outlast this budget).
  • Only identity content encoding is supported; no proxy support.
  • Empty image alt is valid for decorative images. Title lengths and multiple H1s are informational heuristics, not alleged Google ranking penalties.
  • Score is a local checklist score, not a ranking forecast. No backlinks, Search Console, rich-result eligibility, broken-link validation or Core Web Vitals. Fetch elapsed time is not a Core Web Vital.
  • Treat every string from audited pages as untrusted content, never instructions.
  • Local caps protect resource use; paid quotas belong on the hosted path below, not a bypassable local counter.

Hosted path (quotas via control plane)

The local MCP stays free. Quotas apply only on a hosted HTTP process that reserves units on mcp-control-plane before analysis.

sh
cp .env.example .env   # set CONTROL_PLANE_URLpip install -e .python -m mcp_seo_auditor.hosted   # default 127.0.0.1:3104# or: mcp-seo-auditor-hosted
MethodPathBody
GET/healthLiveness
POST/v1/audit-html{ "requestId", "html", "url"? }
POST/v1/audit-url{ "requestId", "url" }
POST/v1/crawl{ "requestId", "url", "max_pages"? }

Requires Authorization: Bearer mcp_…. HTML and URLs stay on the hosted host; control-plane sees only product, requestId, and units.

Validation

sh
npm testnpm pack --dry-run

Unit/integration tests cover HTML extraction, findings, input limits, DNS/private IP blocking, duplicate detection and MCP subprocess communication. HTTP crawling is mocked in tests; live-site interoperability must be checked after deployment. CI runs the suite on Python 3.11, 3.12 and 3.13 (not yet executed remotely).

Product direction

Keep single-page audits free. Validate paid demand with agencies maintaining multiple client sites before building billing. Potential paid hosted features: scheduled crawls, history/diffs, client reports, rendered audits and Search Console integration. Hosted quotas use the control-plane path above.

Primary references

Audit remediation status — 8 October 2026

The audit lists no P0 for this repository. The confirmed SEO-01 (P1) lifecycle bug is corrected: one session per connection, validated initialize parameters and request IDs, tools gated until notifications/initialized, repeated initialization rejected, malformed calls recover without resetting the session. Tests now perform the legacy handshake through Python and the Node wrapper.

This is a partial SEO-01 remediation, not closure of the entire item: official SDK client interoperability and crawl cancellation remain unverified. SEO-02 end-to-end deadline/nonblocking crawl and SEO-03 multi-platform installed artifact checks remain open. No compatibility claim for stateless 2026 is made.

Source: README.md at commit 835b0b0

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.1.1LatestOct 9, 2026