@ranki.io/seo-aeo-mcp

Free SEO + AEO Audit MCP Server for Claude Code, Cursor, Windsurf

The free SEO audit tool, AEO audit tool, Core Web Vitals auditor and image optimizer that lives inside Claude Code, Cursor, Windsurf and ChatGPT Desktop. Your AI editor calls 22 SEO + AEO tools over MCP, fixes the issues directly in your codebase, and proves the score moved — in one conversation. Lighthouse 42 → 96. AEO 38 → 96. No 40-page audit PDFs.

This is the Node / TypeScript edition of Ranki MCP. The hosted PHP server powers mcp.ranki.io; this package is the native-Node alternative, distributed via npm so any MCP-capable client can install it locally with npx.

Quick links

• 🚀 Live demo & install guide · mcp.ranki.io
• 🔑 Get a free Ranki.io API key · required only for the 7 paid bridge tools
• 📖 Developer documentation · REST API, MCP, Skill reference
• 📝 How vibe coders rank on Google + AI search without learning SEO · long-form guide
• 🌐 Ranki.io — AI SEO + AEO automation platform · SaaS that auto-generates ranking content
• 🐙 GitHub source · PHP + TypeScript both included

Install (one line)

npx @ranki.io/cli install

Auto-detects Claude Code / Claude Desktop / Cursor / Windsurf / ChatGPT Desktop and writes the right MCP config. Or use the manual snippets below.

Manual install — Claude Desktop / Claude Code / ChatGPT Desktop (stdio)

Add this to your MCP config:

{
  "mcpServers": {
    "ranki": {
      "command": "npx",
      "args": ["-y", "@ranki.io/seo-aeo-mcp"],
      "env": {
        "RANKI_API_KEY": "rk_live_..."
      }
    }
  }
}

RANKI_API_KEY is optional — only the 7 paid bridge tools need it. The 15 free tools work without an account.

Manual install — Cursor / Windsurf / self-hosted (HTTP)

npx @ranki.io/seo-aeo-mcp --serve --port 8787
# Then point your MCP client at http://127.0.0.1:8787 with X-API-Key header

Binds to 127.0.0.1 by default. Set RANKI_MCP_HOST=0.0.0.0 to expose on a LAN / VPS (read the security section first).

What it actually does — 22 tools

SEO audit, AEO audit, Core Web Vitals (free, 15 tools)

Tool	Purpose
audit_seo	10-check on-page SEO scorecard (title, meta, H1, canonical, viewport, HTTPS, OpenGraph, image alt, internal links, JSON-LD)
audit_aeo	8-check Answer Engine Optimization scorecard (FAQPage / Article schema, definitional intro, author byline, llms.txt, robots AI crawler access, answer-style headings, structured tables)
audit_hidden_pages	Classifies every URL as robots-disallow / noindex / keep / unsure — finds the admin pages, checkouts and search-result URLs that should not be indexed by Google
audit_speed	Real Lighthouse + Core Web Vitals via Google PageSpeed Insights. Returns image opportunities with bytes saved per file, render-blocking JS / CSS, failing on-page SEO audits
audit_core_web_vitals	Focused LCP / CLS / INP audit with literal fix recipes per metric
optimize_images	For each image URL: target format (AVIF + WebP), responsive widths, <picture> block with srcset, the literal sharp-cli / cwebp / avifenc command to run, alt text suggestion
generate_sitemap_xml	Deploy-ready sitemap.xml
generate_llms_txt	The emerging llms.txt standard for telling AI crawlers what your site is about
generate_robots_txt	robots.txt that explicitly allows or denies GPTBot, ClaudeBot, PerplexityBot, Google-Extended
seo_starter_kit	The four baseline files most vibe-coded sites are missing, ready to deploy
find_topic_ideas	Structured brief for 15 article topics across informational / commercial / transactional intent
find_keyword_gap	Methodology for keyword-gap analysis against named competitors
propose_titles_metas	5 title + meta description candidates per page across 5 angles (length-validated)
explain_seo_terms	Reference glossary of 40+ SEO and AEO terms
install_skill	Install commands for the Ranki SEO Skill across every supported AI editor

Your Ranki.io account — real ranking data inside your IDE (paid, 7 tools)

These call the Ranki.io REST API at app.ranki.io. The TypeScript server never opens a database connection — every paid call goes through Laravel's ApiKeyAuth middleware and is scoped to the calling user's data on the server side. No DB credentials, no schema knowledge, no direct DB access in this npm package.

Tool	Purpose
get_account	Whoami — name, email, plan, daily / monthly limits, current usage
list_projects	Lists your Ranki.io projects
list_articles	Paginated index of a project's articles: nano_id, title, status, language, focus keywords, TOC, word count, SEO score
get_article	Single article — title, content_html, focus keywords, TOC, image URLs
list_rank_tracking	28-day Google Search Console summary: totals, top 20 by clicks, top 20 opportunity keywords (the easy wins)
list_gsc_keywords	Full paginated GSC keyword list, sortable
ai_visibility	Recorded AI-citation snapshots: which topics appeared in ChatGPT, Claude, Perplexity and Google AI Overview SERPs

Get an API key at app.ranki.io/developer →

A typical session, condensed

You: audit my site speed and fix the slow images

Claude: → Calling ranki.audit_speed(url="https://myapp.dev")
        ← Lighthouse: 42 perf · LCP 4.8s · 3 images blocking the paint.
        → Calling ranki.optimize_images([hero.png, banner.jpg, card.png])…
        ← 3 files, recipes returned.
        → Running sharp-cli to convert hero.png → hero.avif + hero.webp…
        → Editing app/page.tsx — rewriting <img> as <picture srcset>, adding alt text…
        → Calling ranki.audit_speed again to verify…
        ← Lighthouse: 96 perf · LCP 1.4s.

Two prompts. Lighthouse jumped 54 points. The agent did all the work in your codebase. You reviewed the diff and hit deploy.

Environment

Variable	Purpose
RANKI_API_KEY	API key for the 7 paid bridge tools. Optional for the 15 free tools. Get one at app.ranki.io/developer.
GOOGLE_PSI_API_KEY	Google PageSpeed Insights API key. Optional — without it, audit_speed and audit_core_web_vitals share Google's unauthenticated quota (~1 req/min). With it: 25,000 calls/day.
RANKI_API_BASE	Override the upstream Ranki.io API (default https://app.ranki.io). Self-hosted Ranki.io deployments only.
RANKI_MCP_HOST	Bind interface for --serve (default 127.0.0.1).
MCP_TRUSTED_PROXIES	CSV of CIDR ranges trusted to set X-Forwarded-For / CF-Connecting-IP. Cloudflare ranges are always trusted.

Security

Hardened for public traffic. Same posture as the PHP server at mcp.ranki.io:

• SSRF guard — every outbound fetch validates URL scheme (http/https only), resolves the hostname, and rejects any IP in private / loopback / link-local / reserved / cloud-metadata ranges (incl. AWS IMDS 169.254.169.254). Redirects are followed manually with re-validation at every hop.
• Body size cap — 64 KB hard limit on --serve requests; returns HTTP 413.
• JSON depth cap — depth 16, throws -32700 on deeper input.
• Tool-name allowlist — ^[a-z][a-z0-9_]{0,63}$ before any filesystem touch.
• Atomic daily rate-limit — file-locked counters in /tmp/ranki-mcp-rl/. Same scheme as the PHP impl, so if you run both on one host they share state.
• IP-spoof block — X-Forwarded-For / CF-Connecting-IP headers are honoured ONLY when req.socket.remoteAddress is inside Cloudflare's published ranges (or a MCP_TRUSTED_PROXIES CIDR).
• No DB access — the TypeScript server has zero database code.

The SSRF guard ships with regression tests — see tests/ssrf.test.ts.

Why this matters — AEO is the new SEO

In 2026, the gap between "site renders" and "site ranks" is wider than ever. AI search took 30% of clicks from Google. Most vibe-coded sites have no FAQPage schema, no llms.txt, robots.txt that quietly blocks ClaudeBot, hero images that crush LCP, H2s that AI can't extract as answers — and the dev never learns why ChatGPT doesn't cite them.

Ranki MCP closes that gap programmatically. Your agent does the audit, applies the fix, re-runs the audit. You ship.

Read the full story: How vibe coders rank on Google + AI search without learning SEO →

Develop

npm install
npm run dev          # tsx, hot reload on stdio
npm run build        # → dist/
npm test             # vitest
npm run serve        # HTTP server on :8787

Parity with the PHP server

The PHP server at server/ (production deployment on mcp.ranki.io) and this TypeScript impl expose the same 22 tools, with identical descriptions, the same JSON output, the same SSRF guard, the same rate limits, the same security posture. Tool descriptions in src/tools/registry.ts are kept in lockstep with lib/registry.php. If you find a divergence, please open an issue — it's a bug in one of them.

License

MIT. See LICENSE.

Built by Ranki.io · AI SEO + AEO automation platform.