@automatelab/ai-seo-mcp

AI Citation Toolkit for the Model Context Protocol

![npm version](https://www.npmjs.com/package/@automatelab/ai-seo-mcp) ![license](./LICENSE) ![node](https://nodejs.org)

Audit why AI systems do or do not cite your pages. MCP server. No API keys.

Works inside Claude, Cursor, Windsurf, Codex, and any MCP client that speaks stdio.

---

What it checks

AI crawler access - GPTBot, OAI-SearchBot, ClaudeBot, and PerplexityBot allowed or blocked in robots.txt
llms.txt - present, spec-compliant, links alive
Structured answer extraction - FAQ headings, BLUF paragraphs, answer-ready blocks
[[schema]] completeness - FAQPage, Article, Organization, Person; flags deprecated patterns
Entity clarity - named entity density and sameAs coverage that help AI systems identify the subject
Citation formatting - canonical URL hygiene, og:url, hreflang, noindex traps
Sitemap freshness - lastmod signals that tell crawlers the page is current

---

Run an audit. Get a list of citation-blockers, ranked.

You: Run an AI-SEO audit on https://automatelab.tech/launching-the-ai-seo-mcp/.

Result (truncated):

{
  "url": "https://automatelab.tech/launching-the-ai-seo-mcp/",
  "score": 61,
  "grade": "C",
  "dimension_scores": {
    "schema": 45, "technical": 80, "structure": 40,
    "robots": 90, "freshness": 85, "authority": 40,
    "entity_density": 21, "sitemap": 100
  },
  "findings": [
    {
      "severity": "critical",
      "category": "structure",
      "message": "No FAQ structure found (no FAQPage schema or H3 question headings).",
      "fix": "Add FAQ H3 headings ending in '?' with answer paragraphs, and a FAQPage JSON-LD block.",
      "estimated_impact": "high"
    },
    {
      "severity": "warning",
      "category": "authority",
      "message": "Low authority signals - missing Organization or author Person schema.",
      "fix": "Add Organization JSON-LD and Article.author as a Person node with sameAs links.",
      "estimated_impact": "high"
    }
  ]
}

Each finding names the exact fix. No opaque scores, no guesswork.

---

Install

npx -y @automatelab/ai-seo-mcp

Requires Node 20 or later.

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "ai-seo": {
      "command": "npx",
      "args": ["-y", "@automatelab/ai-seo-mcp"]
    }
  }
}

Restart Claude Desktop. Any MCP client that supports stdio transport works - same command / args pattern.

Optional: headless rendering for SPAs

By default audit_page reads raw HTML — fast, but misses content on React/Vue/Angular SPAs. Pass render: "headless" to spin up Chromium and audit the rendered DOM (adds 3-10s per audit).

One-time install:

npm install playwright-core
npx playwright install chromium

Then call audit_page with render: "headless". Use static for everything else — most marketing sites and docs render fine without it.

---

Run it in CI (GitHub Action)

This repo doubles as a GitHub Action. Drop it in a workflow to fail a PR when any page regresses below an AI-citation score - the same audit engine, gated on every change.

- uses: actions/checkout@v4
- name: AI-SEO audit
  uses: AutomateLab-tech/ai-seo-mcp@v0.5.0
  with:
    urls: "https://example.com,https://example.com/pricing"
    min-score: "70"            # fail if any URL scores below this
    respect-robots: "true"     # set false for staging / sites you own
    report-path: "ai-seo-report.md"   # optional Markdown report artifact
    fail-on-regression: "true"

The Action builds the auditor from the pinned ref, runs audit_page on each URL, writes a scorecard to the job summary, and exits non-zero if any URL falls below min-score (when fail-on-regression is true). Outputs: min_score_observed, urls_audited, report_path. Full example: examples/github-action-usage.yml.

---

| Tool | Purpose | |------|---------| | audit_page | Composite AI-SEO audit with 8-dimension scoring (schema, technical, structure, robots, freshness, authority, entity density, sitemap). | | audit_schema | Validate JSON-LD against Schema.org rules and AI-citation best practice. Flags deprecated patterns. | | audit_canonical | Canonical link integrity, trailing-slash hygiene, og:url consistency. | | audit_site | Single-call site sweep: audit_page + check_robots + check_sitemap + audit_schema with overall grade and top-5 fixes. | | audit_sitemap | Site-wide content audit: stride-sample N URLs from the sitemap, run audit_page on each, return distribution + worst pages + top findings. | | check_robots | Parse robots.txt and report per-crawler allow/disallow for all known AI crawlers. Surfaces the GPTBot-blocked-but-OAI-SearchBot-allowed trap. | | check_sitemap | Validate XML sitemaps: presence, URL count, lastmod freshness, image/video extensions. | | check_technical | HEAD tag audit: canonical, OpenGraph, Twitter Card, hreflang, HTTPS, noindex, title hygiene. | | score_ai_overview_eligibility | Score a page's probability of appearing in Google AI Overviews using current correlation factors. | | score_citation_worthiness | Score how citable a page or text block is for Perplexity, ChatGPT, Google AI Overviews, and Claude. Includes per-section chunk_analysis / extractability_score: how cleanly an LLM can lift a standalone answer from each heading. | | score_agentic_browsing | Score a page against the Lighthouse "Agentic Browsing" category (May 2026): llms.txt, WebMCP, accessibility-tree integrity, and layout stability. | | score_test_citation | Simulate "would an AI engine cite this for this query?" via MCP sampling, with deterministic heuristic fallback. | | llms_txt_generate | Generate llms.txt and optionally llms-full.txt from a domain's sitemap. | | llms_txt_validate | Lint an existing llms.txt for spec compliance and broken links. | | rewrite_aeo | Rewrite content for Answer Engine Optimization (BLUF structure, FAQ format, schema additions). | | rewrite_geo | Rewrite content for Generative Engine Optimization (entity definitions, comparison tables, synthesis-ready structure). | | extract_entities | Extract named entities, sameAs links, and citation-density score from a page's content and structured data. | | diff_pages | Compare two URLs for AI citation-worthiness: side-by-side dimension scores, gap analysis, and prioritized fix recommendations for url_a. | | report_save | Render an audit_page / audit_site result as a Markdown report and write it to disk under MCP_WORKSPACE_ROOT. |

v0.4.0 renamed tools from flat snake_case to dot-notation (audit_page, check_robots, …) for a navigable hierarchy. Update any saved invocations.

Environment variables: see ENV.md.

</details>

---

Contributing

Bug reports, feature ideas, and PRs welcome. See CONTRIBUTING.md.

Security

To report a vulnerability, see SECURITY.md.

License

MIT - see LICENSE.

Built by automatelab.tech

ai-seo