technical-seo-mcp
An MCP server that audits websites for technical and on-page SEO — so you can ask your AI assistant "why isn't this page ranking?" and get a specific, actionable answer.
14 tools covering crawlability, HTTPS, Core Web Vitals, sitemaps, robots.txt,
structured data, international SEO (hreflang), keyword placement, and AI-crawler access. Reports come back as
Markdown, JSON for CI, or a standalone HTML file you can open and send to a client.
No API keys. No accounts. Every check runs directly against the live site.
Table of contents
- Why this exists
- Features
- Screenshots
- Prerequisites
- Quick start
- Supported MCP clients
- Tools
- Usage examples
- Output formats
- Configuration
- Architecture
- Troubleshooting & FAQ
- Roadmap
- Contributing
- Support this project
- Security
- License
- Acknowledgements
Why this exists
SEO tools tend to give you a dashboard. What you usually want is an answer.
Because this runs as an MCP server, your assistant can chain a diagnosis:
audit the page, notice the h1 is missing, read the actual template file,
and propose the fix — in one conversation. The report is designed for that:
every finding says what is wrong and how to fix it, with paste-ready snippets
where they help.
It is also deliberately small: two runtime dependencies, no database, no telemetry, no signup.
Features
- 14 focused tools — one full audit, one site crawl, and twelve individual checks you can run in isolation
- AI-crawler visibility — per-bot
robots.txtstatus for GPTBot, ClaudeBot, Google-Extended, PerplexityBot, and CCBot, plusllms.txtandnoindexdetection in both theX-Robots-Tagheader and the meta tag - Site-wide aggregation —
crawl_auditreports "this problem is on 80% of your pages, fix it once in the template" instead of repeating it per page - Three output formats — Markdown inline, JSON for CI pipelines, or a shareable HTML file
- Regression tracking —
compare_to_baselinediffs against your last run and reports new failures, new warnings, and fixed items - Actionable findings — severity-rated ✅/⚠️/❌, each with the concrete fix
- Fast — every URL is fetched exactly once per audit and shared across checks
- Safe by construction — see Security
Screenshots
HTML report (output: "html") — a standalone file you can open, print, or
send to a client. Sections with findings expand by default; all-clear sections
stay collapsed. All CSS is inlined and nothing is fetched, so it works offline.
Prerequisites
Chrome is auto-detected on macOS, Linux, and Windows. Set CHROME_PATH if yours
lives somewhere unusual. Lighthouse itself is fetched on demand via npx on
first use — no install step, but the first run is slower. The version is pinned
([email protected]), so every run executes the same tested release.
Quick start
Claude Code
claude mcp add technical-seo -- npx -y technical-seo-mcp
Then ask: "Run a full technical SEO audit on example.com"
Three similar names, one project — worth knowing before you edit any config:
Only the package name is fixed. Name the server whatever you like —
seo,audit, anything — by changing the label in your client config.
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"technical-seo": {
"command": "npx",
"args": ["-y", "technical-seo-mcp"]
}
}
}
Config file locations:
- macOS —
~/Library/Application Support/Claude/claude_desktop_config.json - Windows —
%APPDATA%\Claude\claude_desktop_config.json - Linux —
~/.config/Claude/claude_desktop_config.json
Restart Claude Desktop after editing.
Cursor / Windsurf / other clients
Any client that speaks MCP over stdio works with the same command:
{
"mcpServers": {
"technical-seo": {
"command": "npx",
"args": ["-y", "technical-seo-mcp"]
}
}
}
Global install
If you prefer a pinned binary over npx resolution:
npm install -g technical-seo-mcp
seo-mcp --version
Then use "command": "seo-mcp" with no args in your client config.
From source
git clone https://github.com/sourav2024/seo-mcp
cd seo-mcp
npm install
npm run verify # lint + tests + MCP protocol smoke test
claude mcp add technical-seo -- node "$PWD/server.js"
Verify the setup
Two things are worth checking separately, because they fail for different reasons.
1. Does the server itself run? This rules out Node version and install problems:
npx -y technical-seo-mcp --version # prints e.g. 1.0.0
2. Did your client actually connect? A server that runs fine can still fail to register — usually a typo in the config JSON or a config file that wasn't reloaded.
- Claude Code — run
/mcp. You should seetechnical-seolisted as connected. - Claude Desktop — the tools appear under the 🔨 icon in the message box. Restart the app after editing the config; it does not reload on its own.
- Any client — ask "What technical SEO tools do you have?" The assistant
should list
seo_full_audit,crawl_audit, and the twelvecheck_*tools.
3. Run your first audit. This confirms the whole path works end to end:
"Run a full technical SEO audit on example.com"
You should get a report with ✅/⚠️/❌ per check. If any step fails, see Troubleshooting.
There is no build step — the project is plain ESM and runs directly on Node 20+.
Supported MCP clients
"Untested" means the server follows the stdio MCP spec and should work, but no maintainer has verified it. If you use one of these, a confirmation (or a bug report) is welcome.
Protocol support
- stdio transport (no HTTP — see Security)
- Accurate tool annotations: the single checks are
readOnlyHint; the two report tools (seo_full_audit,crawl_audit) can write an HTML file and a baseline, so they arereadOnlyHint: false, destructiveHint: false. None of them ever modifies the audited site - Tool failures return
isError: trueresults rather than protocol errors, so the model can read and react to them - Progress notifications for long operations: pass a
progressTokenandcrawl_audit,seo_full_audit, andrun_lighthousereport as they go - Cancellation: cancelling a request stops the crawl between pages and terminates a running Lighthouse process
structuredContentonoutput: "json", so a client can consume the result object without re-parsing a string
Tools
Site-level audits
Technical SEO
On-page SEO
Not covered, by design
- Keyword research — search volume and difficulty need external paid data (Ahrefs, Semrush, Google Keyword Planner)
- Backlinks / off-page SEO — requires a crawled link index
- Rendered-page visual checks — pair with Playwright MCP for screenshots and JS-rendered inspection
Usage examples
Ask in plain language; the client picks the tool.
A useful pattern: audit, then fix
Because the assistant has both the audit and your codebase, you can go straight from finding to patch:
"Audit localhost:3000, then fix everything you found in the Next.js layout."
CI integration
output: "json" gives you machine-readable results:
{
"target": "https://example.com",
"generated_at": "2026-07-27T10:00:00.000Z",
"counts": { "pass": 18, "warn": 4, "fail": 2 },
"sections": [{ "section": "Page essentials", "checks": [{ "severity": "fail", "text": "..." }] }]
}
Fail a build when counts.fail > 0, or use compare_to_baseline to fail only on
new regressions:
SEO_MCP_STATE_DIR=./.seo-baselines # commit these to track over time
Output formats
seo_full_audit and crawl_audit accept:
output: "markdown"(default) — the report inline, ✅/⚠️/❌ per check.output: "json"— structured per-check severity plus{pass, warn, fail}counts, ready for CI or a dashboard.output: "html"— writes a standalone HTML file and returns its path plus a one-line summary. The markup never goes through the MCP transport, so it costs no context. Sections with findings expand, all-clear sections collapse, and fix snippets render as copyable code blocks. All CSS is inlined and nothing is fetched, so it works offline, overfile://, and as an email attachment. Light/dark aware and print-friendly.output_path— a destination file or directory. Defaults to./seo-report-<host>-<date>.html(seo-crawl-…for crawls).
compare_to_baseline: true— prepends a diff: new failures, new warnings, and fixed items since the last run. The first run saves a baseline.
Baselines are stored per target, one file each, under your OS state directory
(~/Library/Application Support/seo-mcp on macOS, $XDG_STATE_HOME/seo-mcp or
~/.local/state/seo-mcp on Linux, %LOCALAPPDATA%\seo-mcp on Windows) — never
inside the package, which is read-only under npx. Override with
SEO_MCP_STATE_DIR.
Configuration
Every setting is an optional environment variable with a safe default.
Invalid values fall back to the default and log a warning rather than crashing.
See .env.example for the fully commented list.
This server does not read .env files — MCP servers are launched by a client, so
set variables in the client config:
{
"mcpServers": {
"technical-seo": {
"command": "npx",
"args": ["-y", "technical-seo-mcp"],
"env": {
"SEO_MCP_LOG_LEVEL": "debug",
"SEO_MCP_CRAWL_DELAY_MS": "1000"
}
}
}
}
There are no secrets or API keys. Nothing is ever logged that could carry a credential: URL userinfo and credential-bearing query parameters are stripped from log output, and sensitive field names are redacted.
Architecture
server.js MCP tool registration only — no audit logic
src/
config.js All tunables; validated env vars with safe defaults
logger.js Structured stderr logging with redaction
url-guard.js URL validation and SSRF / private-host checks
tool-result.js MCP result shapes and error-message mapping
version.js Version and identity constants
checks/
index.js Registry — re-exports every check
helpers.js Shared fetch, redirect walking, stemming, report parsing
rendering.js JS-shell detection
https.js SSL + http→https redirect classification
urls.js Clean-URL rules
page-essentials.js Title/meta/h1/canonical/OG/viewport/images
caching.js Cache-Control, compression, ETag, size
sitemap.js Sitemap validation, URL sampling, collection
robots.js robots.txt validation
keywords.js Keyword placement + density
structured-data.js JSON-LD / schema.org validation
ai-crawlers.js Per-bot robots status, llms.txt, noindex detection
lighthouse.js Core Web Vitals via npx lighthouse + Chrome detection
crawl.js Multi-page crawl + aggregation
report.js markdown/JSON/HTML output + baseline diffing
html-report.js Standalone HTML renderer (inlined CSS, no subresources)
test/ node:test suites (fixtures, output, guards, logging, config)
scripts/smoke.js End-to-end MCP wire-protocol check
Three design decisions worth knowing:
server.jsholds no audit logic;checks/never touches MCP. That boundary is what makes every check directly unit-testable without a client.- Every URL is fetched exactly once per audit. Checks accept an optional
prefetched
pageand a shared resource cache, so a full audit makes 5 requests — the page,robots.txt,sitemap.xml,llms.txt, and onehttp://redirect probe — instead of re-requesting the page for each of the five checks that need it. - Failures are contained.
Promise.allSettledmeans an unreachable sitemap degrades to one ❌ line instead of losing the whole report, and every tool handler is wrapped so nothing can escape into the transport. - Crawl workers share one queue. Raising
SEO_MCP_CRAWL_CONCURRENCYadds workers that pull from the same queue, so link discovery still reaches pages found by other workers and no URL is fetched twice.
Troubleshooting & FAQ
Common problems — connection failures, missing Chrome, timeouts, permission errors — and answers to recurring questions are in docs/troubleshooting.md.
The fastest first step for almost any issue is debug logging:
{ "env": { "SEO_MCP_LOG_LEVEL": "debug", "SEO_MCP_LOG_FORMAT": "text" } }
All logs go to stderr — stdout carries the MCP protocol.
Roadmap
Not commitments — ideas, roughly in priority order. Feedback welcome.
Next
check_images— deeper image audit (dimensions, formats,srcset, alt quality)- Core Web Vitals from real field data (CrUX API) alongside lab numbers
- Internal-link graph analysis: orphan pages, click depth, anchor-text distribution
Later
- Full DNS-rebinding protection (pin the resolved address for the connection)
- Configurable crawl concurrency with per-host rate limiting
- MCP resources for browsing saved baselines
- MCP prompts for common workflows ("pre-launch checklist", "fix my Core Web Vitals")
- Optional JS rendering behind a flag, for SPA-heavy sites
Under consideration
- A GitHub Action wrapping the JSON output for PR comments
- Competitor comparison (audit N URLs side by side)
Contributing
Contributions are welcome — especially new checks and false-positive fixes. Start with CONTRIBUTING.md, which covers the layout, how to add a check, and what makes a good one.
git clone https://github.com/sourav2024/seo-mcp
cd seo-mcp
npm install
npm run verify # lint + tests + MCP smoke test
By participating you agree to the Code of Conduct.
Security
This server is designed to run locally over stdio, where the URLs it fetches come from you. It defends against hostile content from audited sites: URL scheme validation, per-hop redirect re-validation, HTML escaping in reports, prototype-pollution-safe parsing, body-size caps, and no-shell subprocess spawning.
Two things to know:
- Auditing private hosts works by default (
localhost,10.x,192.168.x). That's intentional and useful locally. - If you expose this to input you don't control, set
SEO_MCP_ALLOW_PRIVATE_HOSTS=false. That enables SSRF protection, blocking private, loopback, and link-local targets — including the169.254.169.254cloud-metadata address — re-checking every redirect hop and the addresses each hostname resolves to.
Full threat model, known limitations, and a hardening checklist: SECURITY.md.
Found a vulnerability? Report it privately — please don't open a public issue.
Support this project
This is free and MIT-licensed, and it stays that way. If it saved you an afternoon of SEO debugging, you can sponsor the work on GitHub.
Things that help just as much and cost nothing: starring the repo, filing a good bug report, or telling me which check produced a false positive on your site.
License
MIT © sourav2024
Acknowledgements
- Model Context Protocol and the TypeScript SDK, by Anthropic
- Google Lighthouse for Core Web Vitals measurement
- Zod for input schema validation
- Google's Search Central documentation and the schema.org vocabulary, which define what most of these checks are checking against