@automatelab/ai-seo-mcp

> AI Citation Toolkit for the Model Context Protocol

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`.

Further reading

• automatelab.tech - teardowns and case studies

MCP tool surface (19 tools)

> 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.

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