{"_id":"technical-seo-mcp","_rev":"4-4f3908e432b8ff9b7087c980c15c8bc6","name":"technical-seo-mcp","dist-tags":{"latest":"1.2.1"},"versions":{"1.0.0":{"name":"technical-seo-mcp","version":"1.0.0","keywords":["mcp","mcp-server","modelcontextprotocol","model-context-protocol","claude","claude-code","seo","technical-seo","seo-audit","on-page-seo","lighthouse","core-web-vitals","sitemap","robots-txt","structured-data","json-ld","schema-org","crawler","site-audit","llms-txt","ai-crawlers"],"author":{"url":"https://github.com/sourav2024","name":"sourav2024"},"license":"MIT","_id":"technical-seo-mcp@1.0.0","maintainers":[{"name":"sourav28","email":"souravkashyap7869@gmail.com"}],"homepage":"https://github.com/sourav2024/seo-mcp#readme","bugs":{"url":"https://github.com/sourav2024/seo-mcp/issues"},"os":["darwin","linux","win32"],"bin":{"seo-mcp":"server.js","technical-seo-mcp":"server.js"},"dist":{"shasum":"d90028bd83f5b046ab7087b4ea5a862325601505","tarball":"https://registry.npmjs.org/technical-seo-mcp/-/technical-seo-mcp-1.0.0.tgz","fileCount":28,"integrity":"sha512-7gWuXQWKgBXhtJ82lkDi6O8jWNBwqszZXpkbjxBLzKx7ds+wj718gOvt4GA1RQYRbi9oDjn6QmM7Le3SItb78A==","signatures":[{"sig":"MEQCIDQr4BlQElzyi3lhVYfH6th/4JjRA/h52pbW215jgclOAiBsydstXbjof2b+Na09Dgf9cSlqY0uBtpOs0cQ5H9TvDg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":174466},"type":"module","engines":{"node":">=20.10.0"},"exports":{".":"./server.js","./checks":"./checks/index.js","./checks/*":"./checks/*.js","./package.json":"./package.json"},"funding":{"url":"https://github.com/sponsors/sourav2024","type":"github"},"gitHead":"d8708fc7ee8280b0e0ac868c2e89bbd637a1b49b","scripts":{"lint":"prettier --check . && markdownlint-cli2","test":"node --test \"test/**/*.test.js\"","build":"echo \"No build step — plain ESM, runs directly on Node 20+\" && node --check server.js","smoke":"node scripts/smoke.js","start":"node server.js","format":"prettier --write .","verify":"npm run lint && npm test && npm run smoke","lint:md":"markdownlint-cli2","test:watch":"node --test --watch \"test/**/*.test.js\"","test:coverage":"node --test --experimental-test-coverage \"test/**/*.test.js\"","prepublishOnly":"npm run check:placeholders && npm test","check:placeholders":"node scripts/check-placeholders.js"},"_npmUser":{"name":"sourav28","email":"souravkashyap7869@gmail.com"},"repository":{"url":"git+https://github.com/sourav2024/seo-mcp.git","type":"git"},"_npmVersion":"11.7.0","description":"MCP server for technical & on-page SEO audits — crawlability, HTTPS, Core Web Vitals, sitemap, robots.txt, structured data, and AI-crawler access. Reports as Markdown, JSON, or a shareable HTML file.","directories":{},"_nodeVersion":"25.3.0","dependencies":{"zod":"^4.4.3","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"prettier":"^3.4.2","markdownlint-cli2":"^0.23.1"},"_npmOperationalInternal":{"tmp":"tmp/technical-seo-mcp_1.0.0_1785429420366_0.9513240922976887","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"technical-seo-mcp","version":"1.1.0","keywords":["mcp","mcp-server","modelcontextprotocol","model-context-protocol","claude","claude-code","seo","technical-seo","seo-audit","on-page-seo","lighthouse","core-web-vitals","sitemap","robots-txt","structured-data","json-ld","schema-org","crawler","site-audit","llms-txt","ai-crawlers"],"author":{"url":"https://github.com/sourav2024","name":"sourav2024"},"license":"MIT","_id":"technical-seo-mcp@1.1.0","maintainers":[{"name":"sourav28","email":"souravkashyap7869@gmail.com"}],"homepage":"https://github.com/sourav2024/seo-mcp#readme","bugs":{"url":"https://github.com/sourav2024/seo-mcp/issues"},"os":["darwin","linux","win32"],"bin":{"seo-mcp":"server.js","technical-seo-mcp":"server.js"},"dist":{"shasum":"6d9672b10d6490905f69d93cde809bdbe0ea9310","tarball":"https://registry.npmjs.org/technical-seo-mcp/-/technical-seo-mcp-1.1.0.tgz","fileCount":29,"integrity":"sha512-VwACeNNFIZtlu4b2bTxh/XWhi6AEDTAkSWIoYXRPVTcDHjvs8DpztWp1HyqvxFpx36xQitoMp+tdvBfQZq4eEg==","signatures":[{"sig":"MEQCIA79rUOcjQrbeaK2QvhtzmrHB2j38SvRY0FddelkZzYHAiAGiBRCPExN3K5dvUW3kX0lbBF6+J4Acf9PCelz89OSvQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":193013},"type":"module","engines":{"node":">=20.10.0"},"exports":{".":"./server.js","./checks":"./checks/index.js","./checks/*":"./checks/*.js","./package.json":"./package.json"},"funding":{"url":"https://github.com/sponsors/sourav2024","type":"github"},"gitHead":"0192463aef80cf13e63fffb019f0fc14c1584d66","scripts":{"lint":"prettier --check . && markdownlint-cli2","test":"node --test \"test/**/*.test.js\"","build":"echo \"No build step — plain ESM, runs directly on Node 20+\" && node --check server.js","smoke":"node scripts/smoke.js","start":"node server.js","format":"prettier --write .","verify":"npm run lint && npm test && npm run smoke","lint:md":"markdownlint-cli2","test:watch":"node --test --watch \"test/**/*.test.js\"","test:coverage":"node --test --experimental-test-coverage \"test/**/*.test.js\"","prepublishOnly":"npm run check:placeholders && npm test","check:placeholders":"node scripts/check-placeholders.js"},"_npmUser":{"name":"sourav28","email":"souravkashyap7869@gmail.com"},"repository":{"url":"git+https://github.com/sourav2024/seo-mcp.git","type":"git"},"_npmVersion":"11.7.0","description":"MCP server for technical & on-page SEO audits — crawlability, HTTPS, Core Web Vitals, sitemap, robots.txt, structured data, and AI-crawler access. Reports as Markdown, JSON, or a shareable HTML file.","directories":{},"_nodeVersion":"25.3.0","dependencies":{"zod":"^4.4.3","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"prettier":"^3.4.2","markdownlint-cli2":"^0.23.1"},"_npmOperationalInternal":{"tmp":"tmp/technical-seo-mcp_1.1.0_1786179363332_0.7727353928121363","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"technical-seo-mcp","version":"1.2.0","keywords":["mcp","mcp-server","modelcontextprotocol","model-context-protocol","claude","claude-code","seo","technical-seo","seo-audit","on-page-seo","lighthouse","core-web-vitals","sitemap","robots-txt","structured-data","json-ld","schema-org","crawler","site-audit","llms-txt","ai-crawlers"],"author":{"url":"https://github.com/sourav2024","name":"sourav2024"},"license":"MIT","_id":"technical-seo-mcp@1.2.0","maintainers":[{"name":"sourav28","email":"souravkashyap7869@gmail.com"}],"homepage":"https://github.com/sourav2024/seo-mcp#readme","bugs":{"url":"https://github.com/sourav2024/seo-mcp/issues"},"os":["darwin","linux","win32"],"bin":{"seo-mcp":"server.js","technical-seo-mcp":"server.js"},"dist":{"shasum":"e7e71b89a1dcbce985c5cbb78acb489ab294ff7e","tarball":"https://registry.npmjs.org/technical-seo-mcp/-/technical-seo-mcp-1.2.0.tgz","fileCount":29,"integrity":"sha512-1b93fC58wJ0FZCXlKlhsSZfN9bH/yqPQWaIEPiaX/qISMNKZCiFdodNue6iXyP4X9j+WXFT0NNRzXP9SLgXlsA==","signatures":[{"sig":"MEUCIQCxqvAO8/f2WoErPTQCdSsP6whqG/xyJZ52rw05ER7MWQIgYW56xl2x98ZmdBvoM7HANYoB6C8Hgv3eYZFnbb65m2o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIC8BYy1+9CXB4wIJwSja3hCJgbyorS58HbaGVN6UOlvnAiEA1gHykBQGDdV8UdKcZ7NWOmS+9GyPfpSqJ1SwlocUh4Q=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/technical-seo-mcp@1.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":201222},"type":"module","engines":{"node":">=20.10.0"},"exports":{".":"./server.js","./checks":"./checks/index.js","./checks/*":"./checks/*.js","./package.json":"./package.json"},"funding":{"url":"https://github.com/sponsors/sourav2024","type":"github"},"gitHead":"d323b3dd37c6d0e4568fec280f5de052a8dcb81d","scripts":{"lint":"prettier --check . && markdownlint-cli2","test":"node --test","build":"echo \"No build step — plain ESM, runs directly on Node 20+\" && node --check server.js","smoke":"node scripts/smoke.js","start":"node server.js","format":"prettier --write .","verify":"npm run lint && npm test && npm run smoke","lint:md":"markdownlint-cli2","skill:zip":"rm -f dist/technical-seo-audit.zip && mkdir -p dist && cd skill/technical-seo-audit && zip -qrX ../../dist/technical-seo-audit.zip . -x '.*' && cd ../.. && unzip -l dist/technical-seo-audit.zip","test:watch":"node --test --watch","test:coverage":"node --test --experimental-test-coverage","prepublishOnly":"npm run check:placeholders && npm test","check:placeholders":"node scripts/check-placeholders.js"},"_npmUser":{"name":"sourav28","email":"souravkashyap7869@gmail.com"},"repository":{"url":"git+https://github.com/sourav2024/seo-mcp.git","type":"git"},"_npmVersion":"10.9.9","description":"MCP server for technical & on-page SEO audits — crawlability, HTTPS, Core Web Vitals, sitemap, robots.txt, structured data, and AI-crawler access. Reports as Markdown, JSON, or a shareable HTML file.","directories":{},"_nodeVersion":"22.23.3","dependencies":{"zod":"^4.6.7","@modelcontextprotocol/sdk":"^1.32.1"},"_hasShrinkwrap":false,"devDependencies":{"prettier":"^3.9.10","markdownlint-cli2":"^0.23.3"},"_npmOperationalInternal":{"tmp":"tmp/technical-seo-mcp_1.2.0_1792217102837_0.041734148284679806","host":"s3://npm-registry-packages-npm-production"}},"1.2.1":{"os":["darwin","linux","win32"],"_id":"technical-seo-mcp@1.2.1","bin":{"seo-mcp":"server.js","technical-seo-mcp":"server.js"},"bugs":{"url":"https://github.com/sourav2024/seo-mcp/issues"},"dist":{"shasum":"f778b6724b1d7968fd6b24d1b931ecfbb3e52ad3","tarball":"https://registry.npmjs.org/technical-seo-mcp/-/technical-seo-mcp-1.2.1.tgz","fileCount":29,"integrity":"sha512-TyzdV8dTrfkelzR1f4DTG7QXunRi2USJlIDsD5HUOaRHkIhk3MNEbiJ1oWy6KeCmZSNaPQHP6M0AfrqIwBRsDw==","signatures":[{"sig":"MEUCIQCIJlgONFf84Z/hnfmSmx5iA5A061h9hvLbAYEgNIMU/QIgCEyIcnz95vnu/D56v6YYbvScnbp3mrymXnBY8ZhX8oQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBp2E7yExnzuSmfEQxAJV4soMpG6u/AjyMVzgdDgMnKeAiEAwA456H5XpQz159TQZyShwxDjzdEp35oqaqcP/J/A3RY="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/technical-seo-mcp@1.2.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":208131},"name":"technical-seo-mcp","type":"module","author":{"url":"https://github.com/sourav2024","name":"sourav2024"},"engines":{"node":">=20.10.0"},"exports":{".":"./server.js","./checks":"./checks/index.js","./checks/*":"./checks/*.js","./package.json":"./package.json"},"funding":{"url":"https://github.com/sponsors/sourav2024","type":"github"},"gitHead":"840500dbb491734d66eecea88ef4a3c67cfe855f","license":"MIT","scripts":{"lint":"prettier --check . && markdownlint-cli2","test":"node --test","build":"echo \"No build step — plain ESM, runs directly on Node 20+\" && node --check server.js","smoke":"node scripts/smoke.js","start":"node server.js","format":"prettier --write .","verify":"npm run lint && npm test && npm run smoke","lint:md":"markdownlint-cli2","skill:zip":"rm -f dist/seo-intelligence.zip && mkdir -p dist && cd skill/seo-intelligence && zip -qrX ../../dist/seo-intelligence.zip . -x '.*' && cd ../.. && unzip -l dist/seo-intelligence.zip","test:watch":"node --test --watch","test:coverage":"node --test --experimental-test-coverage","prepublishOnly":"npm run check:placeholders && npm test","check:placeholders":"node scripts/check-placeholders.js"},"version":"1.2.1","_npmUser":{"name":"sourav28","email":"souravkashyap7869@gmail.com"},"homepage":"https://github.com/sourav2024/seo-mcp#readme","keywords":["mcp","mcp-server","modelcontextprotocol","model-context-protocol","claude","claude-code","seo","technical-seo","seo-audit","on-page-seo","lighthouse","core-web-vitals","sitemap","robots-txt","structured-data","json-ld","schema-org","crawler","site-audit","llms-txt","ai-crawlers"],"repository":{"url":"git+https://github.com/sourav2024/seo-mcp.git","type":"git"},"_npmVersion":"10.9.9","description":"MCP server for technical & on-page SEO audits — crawlability, HTTPS, Core Web Vitals, sitemap, robots.txt, structured data, and AI-crawler access. Reports as Markdown, JSON, or a shareable HTML file.","directories":{},"maintainers":[{"name":"sourav28","email":"souravkashyap7869@gmail.com"}],"_nodeVersion":"22.23.3","dependencies":{"zod":"^4.6.7","@modelcontextprotocol/sdk":"^1.32.1"},"_hasShrinkwrap":false,"devDependencies":{"prettier":"^3.9.10","markdownlint-cli2":"^0.23.3"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/technical-seo-mcp_1.2.1_1792236230144_0.4130962181485829"}}},"time":{"created":"2026-07-30T16:37:00.167Z","modified":"2026-10-17T11:23:50.557Z","1.0.0":"2026-07-30T16:37:00.521Z","1.1.0":"2026-08-08T08:56:03.492Z","1.2.0":"2026-10-17T06:05:02.938Z","1.2.1":"2026-10-17T11:23:50.237Z"},"bugs":{"url":"https://github.com/sourav2024/seo-mcp/issues"},"author":{"url":"https://github.com/sourav2024","name":"sourav2024"},"license":"MIT","homepage":"https://github.com/sourav2024/seo-mcp#readme","keywords":["mcp","mcp-server","modelcontextprotocol","model-context-protocol","claude","claude-code","seo","technical-seo","seo-audit","on-page-seo","lighthouse","core-web-vitals","sitemap","robots-txt","structured-data","json-ld","schema-org","crawler","site-audit","llms-txt","ai-crawlers"],"repository":{"url":"git+https://github.com/sourav2024/seo-mcp.git","type":"git"},"description":"MCP server for technical & on-page SEO audits — crawlability, HTTPS, Core Web Vitals, sitemap, robots.txt, structured data, and AI-crawler access. Reports as Markdown, JSON, or a shareable HTML file.","maintainers":[{"name":"sourav28","email":"souravkashyap7869@gmail.com"}],"readme":"# technical-seo-mcp\n\n**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.**\n\n<!-- The CI and npm badges resolve once the repo is pushed and the package is\n     published; they render as \"unknown\" until then. -->\n\n[![CI](https://github.com/sourav2024/seo-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sourav2024/seo-mcp/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/technical-seo-mcp.svg)](https://www.npmjs.com/package/technical-seo-mcp)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20.10-brightgreen.svg)](https://nodejs.org)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Sponsor](https://img.shields.io/badge/sponsor-%E2%9D%A4-ff69b4.svg)](https://github.com/sponsors/sourav2024)\n\n14 tools covering crawlability, HTTPS, Core Web Vitals, sitemaps, `robots.txt`,\nstructured data, international SEO (hreflang), keyword placement, and AI-crawler access. Reports come back as\nMarkdown, JSON for CI, or a standalone HTML file you can open and send to a client.\n\nNo API keys. No accounts. Every check runs directly against the live site.\n\n---\n\n## Table of contents\n\n- [Why this exists](#why-this-exists)\n- [Features](#features)\n- [Screenshots](#screenshots)\n- [Prerequisites](#prerequisites)\n- [Quick start](#quick-start)\n- [Supported MCP clients](#supported-mcp-clients)\n- [Tools](#tools)\n- [Usage examples](#usage-examples)\n- [Output formats](#output-formats)\n- [Configuration](#configuration)\n- [Architecture](#architecture)\n- [Troubleshooting & FAQ](#troubleshooting--faq)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [Support this project](#support-this-project)\n- [Security](#security)\n- [License](#license)\n- [Acknowledgements](#acknowledgements)\n\n---\n\n## Why this exists\n\nSEO tools tend to give you a dashboard. What you usually want is an answer.\n\nBecause this runs as an MCP server, your assistant can chain a diagnosis:\naudit the page, notice the `h1` is missing, read the actual template file,\nand propose the fix — in one conversation. The report is designed for that:\nevery finding says what is wrong _and_ how to fix it, with paste-ready snippets\nwhere they help.\n\nIt is also deliberately small: two runtime dependencies, no database, no\ntelemetry, no signup.\n\n## Features\n\n- **14 focused tools** — one full audit, one site crawl, and twelve individual\n  checks you can run in isolation\n- **AI-crawler visibility** — per-bot `robots.txt` status for GPTBot, ClaudeBot,\n  Google-Extended, PerplexityBot, and CCBot, plus `llms.txt` and `noindex`\n  detection in _both_ the `X-Robots-Tag` header and the meta tag\n- **Site-wide aggregation** — `crawl_audit` reports \"this problem is on 80% of\n  your pages, fix it once in the template\" instead of repeating it per page\n- **Three output formats** — Markdown inline, JSON for CI pipelines, or a\n  shareable HTML file\n- **Regression tracking** — `compare_to_baseline` diffs against your last run and\n  reports new failures, new warnings, and fixed items\n- **Actionable findings** — severity-rated ✅/⚠️/❌, each with the concrete fix\n- **Fast** — every URL is fetched exactly once per audit and shared across checks\n- **Safe by construction** — see [Security](#security)\n\n## Screenshots\n\n**HTML report** (`output: \"html\"`) — a standalone file you can open, print, or\nsend to a client. Sections with findings expand by default; all-clear sections\nstay collapsed. All CSS is inlined and nothing is fetched, so it works offline.\n\n![HTML SEO audit report showing severity counts and per-section findings](docs/images/html-report.png)\n\n## Prerequisites\n\n| Requirement       | Version    | Notes                                                               |\n| ----------------- | ---------- | ------------------------------------------------------------------- |\n| **Node.js**       | ≥ 20.10    | Uses built-in `fetch` and `node:test`. Check with `node --version`. |\n| **An MCP client** | any        | See [supported clients](#supported-mcp-clients).                    |\n| **Google Chrome** | any recent | **Only** for `run_lighthouse`. The other 13 tools need nothing.     |\n\nChrome is auto-detected on macOS, Linux, and Windows. Set `CHROME_PATH` if yours\nlives somewhere unusual. Lighthouse itself is fetched on demand via `npx` on\nfirst use — no install step, but the first run is slower. The version is pinned\n(`lighthouse@13.5.0`), so every run executes the same tested release.\n\n## Quick start\n\n### Claude Code\n\n```bash\nclaude mcp add technical-seo -- npx -y technical-seo-mcp\n```\n\nThen ask: _\"Run a full technical SEO audit on example.com\"_\n\n> **Three similar names, one project** — worth knowing before you edit any config:\n>\n> | Name                | What it is                                                           |\n> | ------------------- | -------------------------------------------------------------------- |\n> | `technical-seo-mcp` | the **npm package** — what you install                               |\n> | `seo-mcp`           | the **command** it installs (`technical-seo-mcp` also works)         |\n> | `technical-seo`     | the **server name** your client shows; you choose this in the config |\n>\n> Only the package name is fixed. Name the server whatever you like — `seo`,\n> `audit`, anything — by changing the label in your client config.\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"technical-seo\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"technical-seo-mcp\"]\n    }\n  }\n}\n```\n\nConfig file locations:\n\n- **macOS** — `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows** — `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux** — `~/.config/Claude/claude_desktop_config.json`\n\nRestart Claude Desktop after editing.\n\n### Cursor / Windsurf / other clients\n\nAny client that speaks MCP over stdio works with the same command:\n\n```json\n{\n  \"mcpServers\": {\n    \"technical-seo\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"technical-seo-mcp\"]\n    }\n  }\n}\n```\n\n### Global install\n\nIf you prefer a pinned binary over `npx` resolution:\n\n```bash\nnpm install -g technical-seo-mcp\nseo-mcp --version\n```\n\nThen use `\"command\": \"seo-mcp\"` with no `args` in your client config.\n\n### From source\n\n```bash\ngit clone https://github.com/sourav2024/seo-mcp\ncd seo-mcp\nnpm install\nnpm run verify        # lint + tests + MCP protocol smoke test\n\nclaude mcp add technical-seo -- node \"$PWD/server.js\"\n```\n\n### Verify the setup\n\nTwo things are worth checking separately, because they fail for different reasons.\n\n**1. Does the server itself run?** This rules out Node version and install problems:\n\n```bash\nnpx -y technical-seo-mcp --version   # prints e.g. 1.0.0\n```\n\n**2. Did your client actually connect?** A server that runs fine can still fail to\nregister — usually a typo in the config JSON or a config file that wasn't reloaded.\n\n- **Claude Code** — run `/mcp`. You should see `technical-seo` listed as connected.\n- **Claude Desktop** — the tools appear under the 🔨 icon in the message box.\n  Restart the app after editing the config; it does not reload on its own.\n- **Any client** — ask _\"What technical SEO tools do you have?\"_ The assistant\n  should list `seo_full_audit`, `crawl_audit`, and the twelve `check_*` tools.\n\n**3. Run your first audit.** This confirms the whole path works end to end:\n\n> _\"Run a full technical SEO audit on example.com\"_\n\nYou should get a report with ✅/⚠️/❌ per check. If any step fails, see\n[Troubleshooting](docs/troubleshooting.md).\n\nThere is no build step — the project is plain ESM and runs directly on Node 20+.\n\n## Supported MCP clients\n\n| Client               | Status     | Notes                                                      |\n| -------------------- | ---------- | ---------------------------------------------------------- |\n| **Claude Code**      | ✅ Tested  | `claude mcp add technical-seo -- npx -y technical-seo-mcp` |\n| **Claude Desktop**   | ✅ Tested  | Via `claude_desktop_config.json`                           |\n| **Cursor**           | — Untested | Standard stdio MCP config                                  |\n| **Windsurf**         | — Untested | Standard stdio MCP config                                  |\n| **Zed**              | — Untested | Standard stdio MCP config                                  |\n| **Continue.dev**     | — Untested | Standard stdio MCP config                                  |\n| **Custom (MCP SDK)** | ✅         | Anything speaking MCP over stdio                           |\n\n\"Untested\" means the server follows the stdio MCP spec and should work, but no\nmaintainer has verified it. If you use one of these, a confirmation (or a\nbug report) is welcome.\n\n### Protocol support\n\n- stdio transport (no HTTP — see [Security](#security))\n- Accurate tool annotations: the single checks are `readOnlyHint`; the two\n  report tools (`seo_full_audit`, `crawl_audit`) can write an HTML file and a\n  baseline, so they are `readOnlyHint: false, destructiveHint: false`. None of\n  them ever modifies the audited site\n- Tool failures return `isError: true` results rather than protocol errors, so\n  the model can read and react to them\n- **Progress notifications** for long operations: pass a `progressToken` and\n  `crawl_audit`, `seo_full_audit`, and `run_lighthouse` report as they go\n- **Cancellation**: cancelling a request stops the crawl between pages and\n  terminates a running Lighthouse process\n- **`structuredContent`** on `output: \"json\"`, so a client can consume the result\n  object without re-parsing a string\n\n## Tools\n\n### Site-level audits\n\n| Tool             | Checks                                                                                                                                                                                                                                                                                                                                                                                                                               |\n| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `seo_full_audit` | Everything below on one URL, in one report with ✅/⚠️/❌ per item (except Lighthouse). Supports `output: \"json\"`/`\"html\"` and `compare_to_baseline`                                                                                                                                                                                                                                                                                  |\n| `crawl_audit`    | Crawls up to `max_pages` (default 25) seeded from `sitemap.xml` (sitemap-index aware; falls back to internal links), fetching each page once with a polite delay. Aggregates **site-wide issues** (>50% of pages — fix once in the template), **broken internal links**, **multi-hop redirect chains**, **duplicate titles/descriptions**, and **orphan sitemap URLs**. Supports `output: \"json\"`/`\"html\"` and `compare_to_baseline` |\n\n### Technical SEO\n\n| Tool                    | Checks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `check_rendering`       | Fetches the page **without JavaScript** and detects client-side JS shells that Google/AI crawlers struggle to read — recommends SSR/SSG when needed                                                                                                                                                                                                                                                                                                                                                                       |\n| `check_https`           | Valid SSL certificate on `https://`, and a permanent **301** redirect from `http://` (flags temporary 302/307)                                                                                                                                                                                                                                                                                                                                                                                                            |\n| `check_url_structure`   | Clean-URL rules: ≤ ~60 chars, lowercase, hyphens not underscores, no accents, no messy query params, shallow hierarchy. **Offline** — makes no requests                                                                                                                                                                                                                                                                                                                                                                   |\n| `check_page_essentials` | `<title>` presence and length, meta description, exactly one `<h1>`, canonical tag, Open Graph tags, responsive viewport meta, image lazy-loading, WebP/AVIF usage, and explicit image `width`/`height` (CLS risk — no Lighthouse run needed)                                                                                                                                                                                                                                                                             |\n| `check_caching`         | `Cache-Control`, compression (gzip/brotli), `ETag`/`Last-Modified` revalidation, HTML document size                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| `check_sitemap`         | Finds the sitemap like a search engine does (robots.txt `Sitemap:` lines, then `/sitemap.xml`, then common index names), entry count, entry count, admin/cart/checkout URLs that should be excluded, **samples up to 10 `<loc>` URLs** to verify they return 200 with no redirects, and flags missing or stale `lastmod`                                                                                                                                                                                                  |\n| `check_robots`          | `/robots.txt` exists **and is valid** (catches HTML pages or redirects served at that path), references the sitemap, and doesn't accidentally block the whole site                                                                                                                                                                                                                                                                                                                                                        |\n| `check_hreflang`        | **International SEO.** Validates BCP-47 hreflang values (catching `en_US`, `en-UK`, `en-EU`), requires a self-referencing annotation, checks for `x-default`, flags duplicate/conflicting values and relative hrefs, and confirms `<html lang>` agrees. With `verify_return_links: true` it fetches each alternate and verifies reciprocity — **missing return links are the most common reason Google ignores an otherwise-correct cluster**. A single-language site is told hreflang isn't needed, not that it's broken |\n| `check_structured_data` | Extracts schema.org **JSON-LD** (tolerates arrays and `@graph`): Organization (incl. `sameAs`), SoftwareApplication, FAQPage (Question/acceptedAnswer structure), BreadcrumbList. Malformed blocks are flagged with the parse error; no JSON-LD gets a ready-to-paste Organization example                                                                                                                                                                                                                                |\n| `check_ai_crawlers`     | Effective allow/block status per bot — **GPTBot, ClaudeBot, Google-Extended, PerplexityBot, CCBot** — and the `*` default. Checks `/llms.txt`, and flags `noindex`/`nofollow` in **both** the `X-Robots-Tag` header and `<meta name=\"robots\">`, which a plain `robots.txt` check cannot see                                                                                                                                                                                                                               |\n| `run_lighthouse`        | Lighthouse performance + SEO scores and **Core Web Vitals**: LCP (≤ 2.5 s), CLS (≤ 0.1), INP (≤ 200 ms — falls back to TBT when a lab run can't simulate interactions), plus top speed opportunities. Mobile by default. Slow (~1–2 min); requires Chrome                                                                                                                                                                                                                                                                 |\n\n### On-page SEO\n\n| Tool                      | Checks                                                                                                                                                                                                                                                                                                            |\n| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `check_keyword_placement` | Where target keywords appear: `<title>` (and whether front-loaded), URL path, meta description, `<h1>`, `<h2>`s, first ~100 words, image alt text, and keyword density — flagging both thin usage (< 0.3%) and stuffing (> 3%). Matching is **plural/stem-tolerant** (\"freight broker\" matches \"freight brokers\") |\n\n### Not covered, by design\n\n- **Keyword research** — search volume and difficulty need external paid data\n  (Ahrefs, Semrush, Google Keyword Planner)\n- **Backlinks / off-page SEO** — requires a crawled link index\n- **Rendered-page visual checks** — pair with\n  [Playwright MCP](https://github.com/microsoft/playwright-mcp) for screenshots\n  and JS-rendered inspection\n\n## Usage examples\n\nAsk in plain language; the client picks the tool.\n\n| You say                                                                | Tool used                                         |\n| ---------------------------------------------------------------------- | ------------------------------------------------- |\n| \"Run a full technical SEO audit on example.com\"                        | `seo_full_audit`                                  |\n| \"Crawl example.com and find site-wide SEO issues\"                      | `crawl_audit`                                     |\n| \"Audit example.com and give me an HTML report I can send to a client\"  | `seo_full_audit` with `output: \"html\"`            |\n| \"Can GPTBot and ClaudeBot crawl my site?\"                              | `check_ai_crawlers`                               |\n| \"Is my LCP under 2.5 seconds on mobile?\"                               | `run_lighthouse`                                  |\n| \"Check keyword placement for 'freight broker software' on example.com\" | `check_keyword_placement`                         |\n| \"Validate my JSON-LD\"                                                  | `check_structured_data`                           |\n| \"I target the US and Canada — is my hreflang set up right?\"            | `check_hreflang`                                  |\n| \"Do my hreflang alternates all link back to each other?\"               | `check_hreflang` with `verify_return_links: true` |\n| \"Re-audit and tell me what changed since last time\"                    | `seo_full_audit` with `compare_to_baseline: true` |\n| \"Why isn't this page indexed?\"                                         | `check_ai_crawlers` + `check_robots`              |\n\n### A useful pattern: audit, then fix\n\nBecause the assistant has both the audit _and_ your codebase, you can go\nstraight from finding to patch:\n\n> \"Audit localhost:3000, then fix everything you found in the Next.js layout.\"\n\n### CI integration\n\n`output: \"json\"` gives you machine-readable results:\n\n```json\n{\n  \"target\": \"https://example.com\",\n  \"generated_at\": \"2026-07-27T10:00:00.000Z\",\n  \"counts\": { \"pass\": 18, \"warn\": 4, \"fail\": 2 },\n  \"sections\": [{ \"section\": \"Page essentials\", \"checks\": [{ \"severity\": \"fail\", \"text\": \"...\" }] }]\n}\n```\n\nFail a build when `counts.fail > 0`, or use `compare_to_baseline` to fail only on\n_new_ regressions:\n\n```bash\nSEO_MCP_STATE_DIR=./.seo-baselines   # commit these to track over time\n```\n\n## Output formats\n\n`seo_full_audit` and `crawl_audit` accept:\n\n- **`output: \"markdown\"`** (default) — the report inline, ✅/⚠️/❌ per check.\n- **`output: \"json\"`** — structured per-check severity plus `{pass, warn, fail}`\n  counts, ready for CI or a dashboard.\n- **`output: \"html\"`** — writes a **standalone HTML file** and returns its path\n  plus a one-line summary. The markup never goes through the MCP transport, so it\n  costs no context. Sections with findings expand, all-clear sections collapse,\n  and fix snippets render as copyable code blocks. All CSS is inlined and nothing\n  is fetched, so it works offline, over `file://`, and as an email attachment.\n  Light/dark aware and print-friendly.\n  - **`output_path`** — a destination file or directory. Defaults to\n    `./seo-report-<host>-<date>.html` (`seo-crawl-…` for crawls).\n- **`compare_to_baseline: true`** — prepends a diff: **new failures**, **new\n  warnings**, and **fixed items** since the last run. The first run saves a baseline.\n\nBaselines are stored **per target**, one file each, under your OS state directory\n(`~/Library/Application Support/seo-mcp` on macOS, `$XDG_STATE_HOME/seo-mcp` or\n`~/.local/state/seo-mcp` on Linux, `%LOCALAPPDATA%\\seo-mcp` on Windows) — never\ninside the package, which is read-only under `npx`. Override with\n`SEO_MCP_STATE_DIR`.\n\n## Configuration\n\nEvery setting is an **optional** environment variable with a safe default.\nInvalid values fall back to the default and log a warning rather than crashing.\nSee [`.env.example`](.env.example) for the fully commented list.\n\nThis server does not read `.env` files — MCP servers are launched by a client, so\nset variables in the client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"technical-seo\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"technical-seo-mcp\"],\n      \"env\": {\n        \"SEO_MCP_LOG_LEVEL\": \"debug\",\n        \"SEO_MCP_CRAWL_DELAY_MS\": \"1000\"\n      }\n    }\n  }\n}\n```\n\n| Variable                        | Default    | Purpose                                                                  |\n| ------------------------------- | ---------- | ------------------------------------------------------------------------ |\n| `SEO_MCP_LOG_LEVEL`             | `info`     | `silent` \\| `error` \\| `warn` \\| `info` \\| `debug`                       |\n| `SEO_MCP_LOG_FORMAT`            | `json`     | `json` (one object per line) or `text` (human-readable)                  |\n| `SEO_MCP_FETCH_TIMEOUT_MS`      | `20000`    | Per-request timeout (1000–120000)                                        |\n| `SEO_MCP_PROBE_TIMEOUT_MS`      | `15000`    | Timeout for HTTPS/redirect probes                                        |\n| `SEO_MCP_MAX_BODY_BYTES`        | `10485760` | Cap on bytes read per response (64 KB–256 MB)                            |\n| `SEO_MCP_MAX_REDIRECT_HOPS`     | `5`        | Redirect hops before giving up (1–20)                                    |\n| `SEO_MCP_CRAWL_DELAY_MS`        | `500`      | Politeness delay between crawled pages (0–60000)                         |\n| `SEO_MCP_CRAWL_MAX_PAGES`       | `100`      | Hard ceiling on `max_pages` (1–1000)                                     |\n| `SEO_MCP_CRAWL_CONCURRENCY`     | `1`        | Parallel page fetches during a crawl (1–8). Raise only for sites you own |\n| `SEO_MCP_LIGHTHOUSE_TIMEOUT_MS` | `180000`   | Lighthouse run timeout (30000–600000)                                    |\n| `SEO_MCP_LIGHTHOUSE_VERSION`    | `13.5.0`   | Exact Lighthouse version run via `npx` (ranges and tags are refused)     |\n| `SEO_MCP_STATE_DIR`             | OS default | Where baselines are stored                                               |\n| `SEO_MCP_ALLOW_PRIVATE_HOSTS`   | `true`     | Allow auditing localhost / private IPs — see [Security](#security)       |\n| `CHROME_PATH`                   | auto       | Chrome binary for Lighthouse                                             |\n\n**There are no secrets or API keys.** Nothing is ever logged that could carry a\ncredential: URL userinfo and credential-bearing query parameters are stripped\nfrom log output, and sensitive field names are redacted.\n\n## Architecture\n\n```text\nserver.js              MCP tool registration only — no audit logic\nsrc/\n  config.js            All tunables; validated env vars with safe defaults\n  logger.js            Structured stderr logging with redaction\n  url-guard.js         URL validation and SSRF / private-host checks\n  tool-result.js       MCP result shapes and error-message mapping\n  version.js           Version and identity constants\nchecks/\n  index.js             Registry — re-exports every check\n  helpers.js           Shared fetch, redirect walking, stemming, report parsing\n  rendering.js         JS-shell detection\n  https.js             SSL + http→https redirect classification\n  urls.js              Clean-URL rules\n  page-essentials.js   Title/meta/h1/canonical/OG/viewport/images\n  caching.js           Cache-Control, compression, ETag, size\n  sitemap.js           Sitemap validation, URL sampling, collection\n  robots.js            robots.txt validation\n  keywords.js          Keyword placement + density\n  structured-data.js   JSON-LD / schema.org validation\n  ai-crawlers.js       Per-bot robots status, llms.txt, noindex detection\n  lighthouse.js        Core Web Vitals via npx lighthouse + Chrome detection\n  crawl.js             Multi-page crawl + aggregation\n  report.js            markdown/JSON/HTML output + baseline diffing\n  html-report.js       Standalone HTML renderer (inlined CSS, no subresources)\ntest/                  node:test suites (fixtures, output, guards, logging, config)\nscripts/smoke.js       End-to-end MCP wire-protocol check\n```\n\nThree design decisions worth knowing:\n\n1. **`server.js` holds no audit logic; `checks/` never touches MCP.** That\n   boundary is what makes every check directly unit-testable without a client.\n2. **Every URL is fetched exactly once per audit.** Checks accept an optional\n   prefetched `page` and a shared resource cache, so a full audit makes **5\n   requests** — the page, `robots.txt`, `sitemap.xml`, `llms.txt`, and one\n   `http://` redirect probe — instead of re-requesting the page for each of the\n   five checks that need it.\n3. **Failures are contained.** `Promise.allSettled` means an unreachable sitemap\n   degrades to one ❌ line instead of losing the whole report, and every tool\n   handler is wrapped so nothing can escape into the transport.\n4. **Crawl workers share one queue.** Raising `SEO_MCP_CRAWL_CONCURRENCY` adds\n   workers that pull from the same queue, so link discovery still reaches pages\n   found by other workers and no URL is fetched twice.\n\n## Troubleshooting & FAQ\n\nCommon problems — connection failures, missing Chrome, timeouts, permission\nerrors — and answers to recurring questions are in\n**[docs/troubleshooting.md](docs/troubleshooting.md)**.\n\nThe fastest first step for almost any issue is debug logging:\n\n```json\n{ \"env\": { \"SEO_MCP_LOG_LEVEL\": \"debug\", \"SEO_MCP_LOG_FORMAT\": \"text\" } }\n```\n\nAll logs go to stderr — stdout carries the MCP protocol.\n\n## Roadmap\n\nNot commitments — ideas, roughly in priority order.\n[Feedback welcome](https://github.com/sourav2024/seo-mcp/discussions).\n\n### Next\n\n- `check_images` — deeper image audit (dimensions, formats, `srcset`, alt quality)\n- Core Web Vitals from real field data (CrUX API) alongside lab numbers\n- Internal-link graph analysis: orphan pages, click depth, anchor-text distribution\n\n### Later\n\n- Full DNS-rebinding protection (pin the resolved address for the connection)\n- Configurable crawl concurrency with per-host rate limiting\n- MCP resources for browsing saved baselines\n- MCP prompts for common workflows (\"pre-launch checklist\", \"fix my Core Web Vitals\")\n- Optional JS rendering behind a flag, for SPA-heavy sites\n\n### Under consideration\n\n- A GitHub Action wrapping the JSON output for PR comments\n- Competitor comparison (audit N URLs side by side)\n\n## Contributing\n\nContributions are welcome — especially new checks and false-positive fixes.\nStart with [CONTRIBUTING.md](CONTRIBUTING.md), which covers the layout, how to\nadd a check, and what makes a good one.\n\n```bash\ngit clone https://github.com/sourav2024/seo-mcp\ncd seo-mcp\nnpm install\nnpm run verify     # lint + tests + MCP smoke test\n```\n\n- [Report a bug](https://github.com/sourav2024/seo-mcp/issues/new?template=bug_report.yml)\n- [Request a feature](https://github.com/sourav2024/seo-mcp/issues/new?template=feature_request.yml)\n- [Ask a question](https://github.com/sourav2024/seo-mcp/discussions)\n- [Get help](SUPPORT.md)\n\nBy participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## Security\n\nThis server is designed to run **locally over stdio**, where the URLs it fetches\ncome from you. It defends against hostile _content_ from audited sites: URL\nscheme validation, per-hop redirect re-validation, HTML escaping in reports,\nprototype-pollution-safe parsing, body-size caps, and no-shell subprocess\nspawning.\n\nTwo things to know:\n\n- **Auditing private hosts works by default** (`localhost`, `10.x`, `192.168.x`).\n  That's intentional and useful locally.\n- **If you expose this to input you don't control, set\n  `SEO_MCP_ALLOW_PRIVATE_HOSTS=false`.** That enables SSRF protection, blocking\n  private, loopback, and link-local targets — including the\n  `169.254.169.254` cloud-metadata address — re-checking every redirect hop and\n  the addresses each hostname resolves to.\n\nFull threat model, known limitations, and a hardening checklist:\n[SECURITY.md](SECURITY.md).\n\n**Found a vulnerability?** Report it\n[privately](https://github.com/sourav2024/seo-mcp/security/advisories/new) —\nplease don't open a public issue.\n\n## Support this project\n\nThis is free and MIT-licensed, and it stays that way. If it saved you an\nafternoon of SEO debugging, you can\n[sponsor the work on GitHub](https://github.com/sponsors/sourav2024).\n\nThings that help just as much and cost nothing: starring the repo, filing a good\nbug report, or telling me which check produced a false positive on your site.\n\n## License\n\n[MIT](LICENSE) © sourav2024\n\n## Acknowledgements\n\n- [Model Context Protocol](https://modelcontextprotocol.io) and the\n  [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk),\n  by Anthropic\n- [Google Lighthouse](https://github.com/GoogleChrome/lighthouse) for Core Web\n  Vitals measurement\n- [Zod](https://zod.dev) for input schema validation\n- Google's [Search Central documentation](https://developers.google.com/search/docs)\n  and the [schema.org](https://schema.org) vocabulary, which define what most of\n  these checks are checking against\n","readmeFilename":"README.md"}